QR Code Ticketing

This guide walks through the full lifecycle of a QR-code-based pass — from designing its visual layout to validating it at the point of entry. It's the typical setup for event tickets, but applies to any scenario where a pass is presented and scanned as a QR code.

How it works

Step 1: Register target resources

Before creating a QR template, register the resource(s) the ticket should grant entry to — see Physical access control for the resource and resource group setup. Resources are registered in the Access Control service, not via accesspass-srv.

Step 2: Create a pass layout

The layout controls how the ticket looks — branding, colors, and which fields are displayed:

POST /accesspass-srv/layouts
{
  "passLayoutId": "layout-event-qr-default",
  "companyName": "Event Authority",
  "logo": "https://cdn.example.com/event/logo.png",
  "background": "https://cdn.example.com/event/pass-bg.png",
  "fontFamily": "Inter",
  "height": 400,
  "width": 200,
  "primaryColor": "#0B1E3D",
  "secondaryColor": "#FFB703",
  "targetFormat": "svg",
  "displayFields": [
    { "id": "f1", "itemName": "eventName" },
    { "id": "f2", "itemName": "section" },
    { "id": "f3", "itemName": "seat" }
  ]
}

See Create a pass layout. Colors must be valid hex values and dimensions must stay within the supported range.

Step 3: Create a QR-enabled pass template

POST /accesspass-srv/templates
{
  "name": "event-qr-template",
  "description": "QR entry template for event attendance",
  "methods": ["qrcode"],
  "maxValidity": { "value": 12, "unit": "hours" },
  "systemConstraint": { "scopes": ["entry:scan"] },
  "targetResourceRef": {
    "resourceIds": ["device-venue-gate-n1"],
    "resourceGroupIds": ["group:venue:north-gates"]
  },
  "passLayoutIds": ["layout-event-qr-default"]
}

See Create pass template. methods: ["qrcode"] restricts this template to issuing QR tokens, and maxValidity caps how long any pass created from it can remain valid.

Step 4: Issue the pass (ticket)

POST /accesspass-srv/passes
{
  "passUserHolder": { "sub": "sub-fan-120045", "givenName": "Aarav", "familyName": "Sharma" },
  "passUser": { "sub": "sub-fan-120045", "givenName": "Aarav", "familyName": "Sharma" },
  "pass": {
    "title": "Match Day Entry - North Gate",
    "passId": "MATCHPASS-0001",
    "productId": "event-entry",
    "productName": "Event Entry",
    "productInstanceId": "event-2026-03-20",
    "passTemplateId": "event-qr-template",
    "method": "qrcode",
    "validFrom": "2026-03-20T12:00:00Z",
    "validTo": "2026-03-20T23:00:00Z",
    "customFields": { "eventName": "Season Opener", "section": "North Stand", "seat": "N-21-045" },
    "targetResourceRef": { "resourceIds": ["device-venue-gate-n1"] }
  }
}

The response contains the QR token:

{
  "success": true,
  "data": {
    "passId": "MATCHPASS-0001",
    "token": "<qr-token-value>"
  }
}

See Create a new pass. validFrom/validTo must fit within the template's maxValidity, and targetResourceRef on the pass must be compatible with the template's policy.

Step 5: Render the QR code

Encode the returned token as a QR code in your app, mobile wallet screen, PDF e-ticket, or email. Keep the QR payload limited to the token itself — avoid embedding extra metadata, and avoid logging the raw token in frontend analytics.

Step 6: Introspect the QR code at the checkpoint

POST /accesspass-srv/passes/qrcode/introspect
{
  "token": "<qr-token-value>",
  "access_method": "qrcode",
  "strictValidation": true,
  "targetResourceRef": { "resourceIds": ["device-venue-gate-n1"] }
}

See Introspect (validate) a pass. Always include the targetResourceRef of the actual scanner/gate — this is what prevents a valid ticket for one entrance being used at another. A response with active: true authorizes entry; treat active: false as an authoritative deny.

Related APIs

Endpoints used in this guide. For the full API surface, see the Access Pass API reference.

Operation	Method	Path	Description	Link
Create pass layout	POST	/accesspass-srv/layouts	Visual ticket design (branding, fields).	View API
Create pass template	POST	/accesspass-srv/templates	QR-enabled template with methods: ["qrcode"].	View API
Create pass	POST	/accesspass-srv/passes	Issues the ticket and returns the QR token.	View API
Introspect pass	POST	/accesspass-srv/passes/qrcode/introspect	Validates the token at the gate.	View API

Example variants

• General admission: targetResourceRef.resourceGroupIds = ["group:venue:north-gates"] — valid at any gate in that group.
• VIP access: a separate template scoped to resourceIds: ["device-venue-vip-lounge-01"] with an additional custom field (e.g. "tier": "platinum"). The general-admission ticket fails introspection at this resource, and vice versa.

Checklist

• Design the layout and create the QR-enabled template before issuing passes.
• Keep validFrom/validTo within the template's maxValidity.
• Introspect with the actual scanner/gate's targetResourceRef, not just the token.
• Treat the introspection result as the authoritative entry decision.