Access ticketing provider integration
Access controls venue admission. Your ticketing system tells Access which tickets exist and which matches they cover. Access uses its configured sections and entrances to decide whether a scan opens the gate. You cannot set entrances, section to entrance mappings, or scan limits in a request.
A ticket is one pass. The pass routes described here maintain one current match for that pass. Sending a different match moves the pass, and revoking it removes all its active match bindings. These routes do not support adding a second match to the same pass or revoking just one of several matches. Contact eventii to agree the integration for season tickets covering multiple matches.
Get started
Contact eventii to onboard. We will agree on your tenant, event and section identifiers, and the destination for physical entry webhooks. We will then give you an API key. The key identifies your tenant and integration, so requests do not include a tenant or provider name.
Use <access-base-url> as the base URL, with all ingress routes under /. eventii supplies the base URL for each environment. Send your API key in x-api-key on every request. A request without a valid key is refused. The x-request-id header is optional on every request, including cancel. Request and response bodies use JSON. Use camelCase field names in your requests as shown below. Unknown fields are ignored. There is no GET route to read a pass back.
The events and sections you refer to must exist in Access. You can send a pass for an event that Access does not know yet. Access keeps it and connects it when the event is created, but the pass cannot admit anyone before that.
Send a pass
POST <access-base-url>/v1/ingress/passes
x-api-key: <your key>
x-request-id: <unique id per change>
Content-Type: application/json
{
"entityId": "ticket-123",
"eventId": "11111111-2222-4333-8444-555555555555",
"projectionVersion": 1,
"barcode": "0123456789",
"sectionId": "north-stand",
"rowNumber": "12",
"seatNumber": "18",
"priceCategoryId": "adult",
"priceCategoryName": "Adult",
"passHolderId": "customer-789",
"passHolderName": "Ada Example",
"productId": "season-2026",
"productName": "2026 season ticket",
"passType": "SeasonTicket",
"biometricReference": "wicket-person-id"
}
| Field | Meaning | Max length |
|---|---|---|
entityId | Your stable identity for the ticket. It never changes, also when the barcode does. | 128 |
eventId | Your match identifier as a GUID, mapped to the Access event for your integration. Use the mapping agreed during onboarding. | 128 |
projectionVersion | Required positive integer. Increase it for every change to the same entityId, including a revoke or reinstatement. Reuse it only for an identical retry. | Not applicable |
barcode | What the gate scans. Use at least 4 characters. Leading and trailing whitespace is trimmed. | 64 |
sectionId | Section used for entrance routing. Access maps it to entrances. | 32 |
rowNumber, seatNumber | Seat, for display. | 16 each |
priceCategoryId, priceCategoryName | Price category. Access can route by price category. | 128 each |
passHolderId, passHolderName | The holder. On success, the gate shows its configured welcome lines, without the holder name or section. | 128 each |
productId, productName | What the holder bought, for display and reporting only. Access never routes or validates on the product. | 128 each |
passType | A free text label kept as sent. The expected values are Ticket and SeasonTicket. | 128 |
active | Optional. Leave it out, or send true, for everything except a revoke. | Not applicable |
biometricReference | Optional. The holder's face recognition id. See below. | 256 |
Lengths are in characters. You must respect every maximum length above, including the 128 character limit for each of productId, productName, priceCategoryId, priceCategoryName, and passType. Do not rely on a particular status code or error response format if you exceed these limits.
Use eventId for the match and productId for the purchase. A product does not add matches to a pass. Sending the product id as eventId means the pass never connects to a match.
Send the full current state each time. entityId, eventId, barcode, and projectionVersion are required on a push. Other pass fields you leave out are cleared, so this is not a partial update. The one exception is biometricReference, described below. You may omit passHolderName. The pass then has no holder name; the successful gate display still uses the configured welcome lines.
Access looks up a pass by entityId. Send the same entityId and eventId with a higher projectionVersion to update it. A different eventId moves the pass to that match and revokes its previous bound match. It does not add another match. Barcode, holder, section, seat, price category, and product apply to the whole pass. Keep one increasing version sequence per entityId, including across moves. Requests at or below the last applied version change nothing, even if they return 202 Accepted.
To reprint a ticket, push the same entityId and eventId with the new barcode and a higher projectionVersion. Access replaces the barcode in place and sends the change to scanning asynchronously. The old barcode may still admit until the notification is processed, and any offline grants already delivered remain usable until their expiry. The new barcode is used for the pass's active match bindings once the change reaches scanning.
You can also send PUT to the same path with exactly the same behavior as POST.
A ticket that an Access operator has cancelled stays cancelled. A push from your system does not bring it back.
Revoke a pass
To revoke all active match bindings of a pass, send its entityId, current eventId, and a higher projectionVersion with active set to false. Do not use this request to release just one match from a pass covering several matches:
POST <access-base-url>/v1/ingress/passes
x-api-key: <your key>
x-request-id: <unique id per change>
Content-Type: application/json
{
"entityId": "ticket-123",
"eventId": "11111111-2222-4333-8444-555555555555",
"projectionVersion": 2,
"active": false
}
Every active match binding of the pass is revoked, even if the supplied eventId names a different match. The pass still exists, and its barcode, holder, and seat are untouched. You do not send a barcode with a revoke.
Retry a revoke with the same projectionVersion. Access remembers its version even for an unknown ticket, so an older or equal version cannot later create or reinstate the pass. To reinstate the intended match, send the full current state with the same entityId, that match's eventId, and a higher projectionVersion. This does not restore other revoked matches.
A holder who already entered before the revoke keeps that entry. Revocation reaches scanning through asynchronous notification, so it does not guarantee immediate refusal. Offline grants already delivered remain usable until their expiry.
Cancel a ticket
DELETE <access-base-url>/v1/ingress/passes/{entityId}
x-api-key: <your key>
x-request-id: <unique id per change>
Do not send a request body.
Cancel uses only entityId. The barcode is not involved. It cancels the ticket for every match. The change reaches scanning asynchronously, and offline grants already delivered remain usable until their expiry.
Cancel is permanent. A later POST or PUT for the same entityId returns 202 Accepted but changes nothing. The pass stays cancelled. To reassign a ticket, send a normal push with the new holder and seat. Do not cancel and add it again.
Revoke with active: false to remove all active match bindings when the pass may be reinstated later. Cancel when the ticket is gone for good.
A holder who entered before the cancel keeps that entry. Cancellation does not guarantee immediate refusal of future entry because of the notification delay and offline grant expiry described above.
Repeating a cancel changes nothing and still returns 202 Accepted. A cancel for an unknown entityId also returns 202 Accepted. Access logs it but stores nothing. A later push for that entityId creates a normal pass that admits. Cancel only after the push that created the ticket succeeded.
| Status | Meaning |
|---|---|
202 Accepted | The request was accepted. This includes a request that changed nothing. |
200 OK | Nothing changed. The request id was already completed, the pass belongs to a different integration than your key, or the cancel could not be applied. Contact eventii if the ticket still admits. |
404 Not Found | Your key is not connected to an integration. Contact eventii. |
Face recognition id
If the club uses face recognition, send the holder's provider ID as biometricReference with the pass. Access stores only this reference. It does not receive or store face data. Ingress redacts the biometricReference field in logged request bodies and ingress action log payloads.
Send it on every push for the ticket. Access applies these rules:
- A value replaces the stored one when it is different.
- Leaving the field out keeps the stored value.
- An empty value removes the stored one.
- The value can be at most 256 characters.
- When a push carries a
passHolderIdthat differs from the stored one, or supplies one where none was stored, and it has nobiometricReference, Access removes the stored face id. This is why you should send the face id together with the holder on every push: a face id is only kept when Access can tell it still belongs to the same holder.
Responses and retries
| Status | Meaning |
|---|---|
202 Accepted | The request was accepted. This includes a request that changed nothing. |
200 OK | The x-request-id belongs to a request Access already completed, so nothing was done again. |
400 Bad Request | The request failed validation, for example because projectionVersion is missing or is not positive. These validation responses are JSON problem documents listing the errors. Exceeding a field's maximum length does not guarantee this response. |
404 Not Found | Your key is not connected to an integration. Contact eventii. |
The cancel route has its own response table above.
Use a new x-request-id for each business change. Reuse the same one only to retry an identical request after a failure. Replay protection by request id is best effort. For pushes and revokes, also retain the original projectionVersion on retries, so an older retry cannot overwrite a newer change.
Receive physical entry webhooks
After a successful physical entry, Access sends a PassEntered webhook to your endpoint. This is separate from the eventii Open API webhooks in Webhooks, which have different events, payloads, credentials, and delivery behavior and are managed with an Open API key. Only a resolved pass with a Valid or Spectator result produces this Access webhook. Validation scans, resets, access card activity, and denied scans do not.
Access sends JSON with POST. Return any 2xx response once you have accepted the event. The event type is in X-Eventii-Event-Type: PassEntered, and the stable X-Eventii-Event-Id header is the key to deduplicate on.
{
"EntityId": "ticket-123",
"EventId": "11111111-2222-4333-8444-555555555555",
"ProductId": "season-2026",
"SectionId": "north-stand",
"PassType": "SeasonTicket",
"EntranceName": "North entrance",
"EnteredTimestamp": "2026-09-21T18:42:15"
}
The payload is flat and uses PascalCase. A field without a value is left out. EntityId and EventId are your identifiers, not Access internal ones. EnteredTimestamp is the club's local time with no offset. If the club time zone is not available, it is the entry instant in UTC, still without an offset.
Verify the signature
We agree how your endpoint is authenticated during onboarding: None, Bearer, Basic, Header, or Query. For signed deliveries, verify the raw request bytes before you parse the JSON. The X-Eventii-Signature header looks like this:
t=unix-timestamp,v1=lowercase-hex-hmac-sha256
The timestamp is Unix time in whole seconds, written as decimal digits. The digest is 64 lowercase hexadecimal characters. Compute an HMAC SHA 256 with the signing secret agreed during onboarding over the UTF-8 bytes of:
timestamp + "." + rawBody
Use the signing secret as given, encoded as UTF-8. Do not hash, hex decode, Base64 decode, or trim it. This secret is separate from the credential used to authenticate deliveries to your endpoint.
The examples below compare digests in constant time and reject timestamps more than 300 seconds old or more than 300 seconds in the future. Each retry has a fresh timestamp. Still deduplicate on X-Eventii-Event-Id, because a timestamp check does not prevent replay within the window.
Verify the raw body before parsing JSON. Do not reserialize it, normalize whitespace, or change encoding. Reject malformed headers and failed verification, then parse and process only authenticated requests.
C# (.NET 10): pass the untouched request body as byte[] rawBody, the signature header value, and your signing secret.
using System;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
static bool VerifyWebhook(byte[] rawBody, string signature, string secret)
{
var match = Regex.Match(signature, @"\At=([0-9]{1,12}),v1=([0-9a-f]{64})\z");
if (!match.Success)
{
return false;
}
var timestampText = match.Groups[1].Value;
var timestamp = long.Parse(timestampText, CultureInfo.InvariantCulture);
var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
if (Math.Abs(now - timestamp) > 300)
{
return false;
}
var prefix = Encoding.UTF8.GetBytes(timestampText + ".");
var signedBytes = new byte[prefix.Length + rawBody.Length];
Buffer.BlockCopy(prefix, 0, signedBytes, 0, prefix.Length);
Buffer.BlockCopy(rawBody, 0, signedBytes, prefix.Length, rawBody.Length);
var expected = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), signedBytes);
var received = Convert.FromHexString(match.Groups[2].Value);
return CryptographicOperations.FixedTimeEquals(expected, received);
}
Node.js (ES module): rawBody must be a Buffer captured before JSON middleware.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyWebhook(rawBody, signature, secret) {
const match = /^t=([0-9]{1,12}),v1=([0-9a-f]{64})$/.exec(signature);
if (!match || match[0] !== signature) {
return false;
}
const timestamp = Number(match[1]);
if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) {
return false;
}
const expected = createHmac('sha256', Buffer.from(secret, 'utf8'))
.update(Buffer.from(match[1] + '.', 'utf8'))
.update(rawBody)
.digest();
const received = Buffer.from(match[2], 'hex');
return timingSafeEqual(expected, received);
}
Access attempts a delivery up to eight times. It uses a five second polling interval after each delivery batch. Processing time and queued deliveries extend the time between attempts, so retries are not exactly five seconds apart. Your receiver must handle duplicate events and must not expect the delay between attempts to grow with each retry.
Troubleshooting
If a push or cancel does not take, contact the club's eventii contact with your x-request-id if you sent one, entityId, eventId, and the request timestamp. They can check the ingress action log for the request and its outcome. A cancel for a pass your key does not own returns 200 OK and does not cancel the pass.
Checklist
- Use the key you were given and one
entityIdper ticket for its whole life. - Send the full current state with an increasing
projectionVersionperentityId. Keep the version unchanged on an identical retry. - Keep the same
eventIdfor updates. Changing it moves the pass and revokes the previous bound match. - Revoke all active match bindings with
active: false, and reinstate the intended match with a higher version. These routes cannot add a second match to the same pass. - Cancel a ticket for good with
DELETE. It cannot be reinstated. Reassign by pushing the new holder instead. - Allow for asynchronous notification after a move, reprint, revoke, or cancel. Offline grants already delivered remain usable until their expiry.
- Send
biometricReferencewith every push if the club uses face recognition. - Use a new
x-request-idfor each change and reuse it only to retry. - Verify webhook signatures from the raw bytes, answer
2xx, and deduplicate onX-Eventii-Event-Id.