Access Pass

Overview

Access Pass is cidaas's digital pass and ticket management capability. It replaces physical tickets, badges, and cards with digital credentials — for example event tickets, membership cards, employee badges, or API access grants — that tie a verified cidaas identity to an access permission for a physical location or a digital resource.

Passes are issued from pass templates and rendered using pass layouts, and are presented and validated via QR code, NFC, a mobile app, or a Personal Access Token (PAT).

Access Pass configuration model

Configuration falls into two groups:

• Managed by accesspass-srv — pass templates, pass layouts, and issued passes (including methods, scopes, and validity).
• Referenced from Access Control (Trustdesk) — resource catalog entries linked by ID via targetResourceRef. accesspass-srv stores the reference; the catalog is managed outside the pass service.

┌─────────────────────────────────────────────────────────────────┐
│                 ACCESS PASS CONFIGURATION MODEL                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────┐   references (IDs)   ┌──────────────────┐ │
│  │  Pass Template   │◄───────────────────►│   Pass Layout    │  │
│  │   (blueprint)    │    passLayoutIds    │ (visual design)  │  │
│  └──────────────────┘                    └──────────────────┘   │
│         │                                                       │
│         │ references (IDs)              ┌──────────────────┐    │
│         └──────────────────────────────►│ Resource Catalog │    │
│              targetResourceRef          │ (Access Control  │    │
│                                         │  service)        │    │
│         issues                          └──────────────────┘    │
│         ▼                                                       │
│  ┌──────────────────┐                                           │
│  │      Pass        │  method: qrcode | nfc | pat | …           │
│  │   (credential)   │                                           │
│  └──────────────────┘                                           │
│         │                                                       │
│         │ presentation + introspection (runtime)                │
│         ▼                                                       │
│  ┌──────────────────┐                                           │
│  │ Gate / API /     │  POST …/passes/{method}/introspect        │
│  │ Scanner          │ ────────────────► accesspass-srv          │
│  └──────────────────┘                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key relationships

• Pass Template ↔ Pass Layout: The template references layout IDs via passLayoutIds. Layouts are optional — PAT passes typically need no visual layout.
• Pass Template / Pass ↔ Resource Catalog: targetResourceRef binds a template or pass to catalog resource and group IDs. Those IDs must exist in the Access Control service before template creation succeeds.
• Pass Template → Pass: Issuing a pass applies the template policy and returns a presentation token (qrcode, nfc, cpat-..., etc.).
• Pass → Introspection: At runtime, a gate, scanner, or protected API calls accesspass-srv to validate the token, scopes, and (when configured) the resource being accessed.

Choosing a use case

Use case	Access method	How the pass is presented	What controls access	targetResourceRef
QR code ticketing	qrcode	QR code on ticket, app, or PDF	Introspection at the gate with the scanned resource	Required
NFC access	nfc	Tap on NFC card, wristband, or device	Introspection at the reader with the tapped resource	Required
Personal Access Token (PAT)	pat	Authorization: Bearer cpat-... on API calls	Scopes checked on every introspection call	Optional
Physical access control	qrcode, nfc, …	Scanner or reader at a door, gate, or turnstile	Pass bound to Resource Catalog entries; introspection must match the resource being accessed	Required

Physical access control describes the resource-binding model (Resource Catalog + targetResourceRef) used by QR and NFC at entry points. PAT reuses the same catalog optionally when a token must be limited to specific APIs beyond scopes.

Where to configure

Trustdesk path	Purpose
Passes → Access Pass (/passes)	Issue and manage individual passes
Passes → Pass Templates (/pass-templates)	Define templates: allowed access methods, scopes, and rules that passes created from them must follow
Passes → Pass Layouts (/pass-layouts)	Design the visual layout (branding, colors, display fields) used to render a pass

Requires the PASS_VIEWER role to view, and PASS_MANAGER (or ADMIN/SECONDARY_ADMIN) to manage passes, templates, and layouts.

Key concepts

Concept	Description
Pass	A single issued digital credential (ticket, badge, or token) created from a pass template.
Pass Template	An admin-defined blueprint that specifies the allowed access methods, scopes, and validation rules for passes created from it.
Pass Layout	The visual design (background, logo, colors, display fields) applied when rendering a pass.
Resource Catalog	The registry of zones, devices, or digital assets a pass can grant access to. Managed by the Access Control service (Trustdesk), not accesspass-srv — see Physical access control.
Resource Group	A named grouping of catalog resources (e.g. "all north gates") used to assign access in bulk instead of per-resource.
targetResourceRef	Binds a template or pass to catalog resources (resourceIds) and/or resource groups (resourceGroupIds). For QR/NFC/physical access, introspection should include the resource being accessed. For PAT, this is optional — scopes are usually sufficient; use targetResourceRef only to restrict which API/service a token works against.
Personal Access Token (PAT)	An opaque token (cpat-...) issued as a pass, validated via introspection rather than signature verification.

Technical APIs

The full Access Pass API is documented in the Access Pass API reference. Each use case guide lists the endpoints relevant to that flow:

Guide	APIs covered
QR code ticketing	Pass layout, template, pass creation, QR introspection
NFC access	Pass layout (optional), template, pass creation, NFC introspection
Personal Access Token (PAT)	Template, pass creation, PAT introspection, revoke
Physical access control	Template and pass with targetResourceRef, introspection at resource

For pass management beyond these flows (state changes, transfer, graph search, layout CRUD), browse the complete endpoint list in the API reference.