Physical Access Control

This guide explains how a pass grants entry to a physical location — a door, gate, or turnstile — by binding it to a resource registered in the Access Control service.

How it works

A pass (or its template) carries a targetResourceRef, which references specific resources (resourceIds) and/or resource groups (resourceGroupIds) from the Resource Catalog. At the point of entry, a scanner or control backend introspects the presented pass together with the actual resource being accessed. Access is only granted if the pass is active and its targetResourceRef matches the resource being scanned — a valid pass for one gate does not automatically work at another.

Where resources are registered

The Resource Catalog is managed by the Access Control service (Trustdesk UI or its API) — not by accesspass-srv. When you set targetResourceRef on a pass template or pass, accesspass-srv only references catalog IDs; template creation fails validation if those IDs do not exist in the catalog.

PAT integrations that need API binding reuse this same catalog model — see Personal Access Token (PAT).

Step 1: Register target resources

Before creating a template or pass with a targetResourceRef, the resources it should grant access to must exist in the Resource Catalog.

Create a resource group to act as a policy boundary for a set of resources (for example all gates on one side of a venue):

{
  "id": "group:venue:north-gates",
  "name": "North Gates",
  "description": "Entry gates on the north side"
}

Register a physical resource (a door or turnstile) and attach it to a group:

{
  "id": "device-venue-gate-n1",
  "name": "North Gate Controller 1",
  "resourceType": "door",
  "groupId": "group:venue:north-gates"
}

Register a digital resource (for example an API a PAT should be bound to):

{
  "id": "api-analytics-v1",
  "name": "Analytics API v1",
  "resourceType": "digital-asset",
  "groupId": "group:partner-apis"
}

Use resourceGroupIds in templates/passes for broad access policy, and resourceIds for exceptions or single-resource targeting. Keep resource and group IDs stable — pass templates and passes reference them directly, and changing an ID after go-live breaks existing mappings.

Step 2: Reference resources in the pass template or pass

When creating a pass template (or a pass directly), bind it to the resources it should unlock:

{
  "targetResourceRef": {
    "resourceIds": ["device-venue-gate-n1"],
    "resourceGroupIds": ["group:venue:north-gates"]
  }
}

See Create pass template and Create a new pass.

Step 3: Validate and trigger access at runtime

At the point of entry, introspect the presented pass together with the actual resource being scanned:

POST /accesspass-srv/passes/{method}/introspect
{
  "token": "<presented-token>",
  "targetResourceRef": {
    "resourceIds": ["device-venue-gate-n1"]
  }
}

See Introspect (validate) a pass.

A response with active: true confirms the pass is valid and authorized for that specific resource. Only then should the connected access control resource be triggered (e.g. unlocking the gate). Different resources — for example a main entrance vs. a VIP area — are protected independently: a pass scoped to the main entrance will fail introspection at a VIP-only resource.

Example: two independent access levels

• Main entrance: a general-admission pass with targetResourceRef.resourceGroupIds = ["group:venue:north-gates"] opens any north gate.
• VIP area: a separate pass template targets only resourceIds: ["device-venue-vip-lounge-01"]. The general-admission pass fails introspection at this resource, and vice versa.

Related APIs

Resource Catalog entries are managed in the Access Control service (Trustdesk), not via accesspass-srv. The endpoints below are used to bind passes to catalog resources and validate access at runtime. For the full API surface, see the Access Pass API reference.

Operation	Method	Path	Description	Link
Create pass template	POST	/accesspass-srv/templates	Template with targetResourceRef to catalog IDs.	View API
Create pass	POST	/accesspass-srv/passes	Issues a pass bound to specific resources.	View API
Introspect pass	POST	/accesspass-srv/passes/{method}/introspect	Validates token + resource match at entry.	View API

Step-by-step setup for specific presentation methods: QR code ticketing, NFC access, PAT.

Checklist

• Register resources and resource groups before referencing them.
• Bind targetResourceRef at the template level (shared policy) and/or the pass level (per-pass override).
• Always introspect with the actual resource being accessed, not just the token.
• Trigger the physical/digital action only after a successful (active: true) introspection response.