Overview
Organizations use Passinstance to replace physical plastic keycards and badges with secure, branded digital credentials in Apple Wallet and Google Wallet. Staff, contractors, students, and facility visitors access office buildings, co-working campuses, and restricted labs using optical 2D barcode turnstiles or contactless NFC tap readers.
Backend Architecture & Visual Schema
Identity passes are designed with high-visibility employee metadata and anti-counterfeiting visual safeguards:
Visual Layout & Asset Slots
-
Pass Type (pass type):
studentId,generic, orposterGeneric(Apple Wallet and Google Wallet present these with dedicated identity card proportions). -
HRIS & Directory Correlation (
externalId): Store your directory/HR employee ID inexternalId(max 255 chars, unique across live tenant passes) so automated offboarding webhooks can void or update passes viaPOST /api/v1/passes/upsert-by-external-idorGET /api/v1/passes/by-external-id/:externalId. -
Catalog Demo Templates:
student-id-card,daily-access-pass, andconference-badge. -
Photo Identification: Upload staff portrait photos to the
thumbnailasset slot (90x90 pt at @1x, 270x270 px at @3x). Google Wallet renders this as a prominent circular or square avatar. -
Organization Branding: Fixed
logoandstripbanner displaying company or campus colors. -
Dynamic Employee Metadata:
- primaryFields: Employee Full Name ({fullName}). - secondaryFields: Job Title ({title}) and Department ({department}). - auxiliaryFields: Employee ID ({employeeId}) and Security Clearance ({clearanceLevel}). - backFields: Emergency building protocols, safety contact phone numbers, and IT service desk links.
-
Anti-Screenshot Dynamic Animation (
addSecurityAnimation: true): Generates an animated, time-varying visual perimeter on the pass to prevent static screen captures or shared photo deception.
Access Control Mechanics & Attendance Tracking
For daily facility attendance, shift tracking, or lunch allowance monitoring, identity passes can attach interactive mechanics:
-
Mechanic Type:
VALID_ONCE_PER_DAY. -
Timezone Resolution (
resolveCustomerTimeZone): ThePass Mechanics Engineresolves the passholder's building location timezone (e.g.Europe/London). Once scanned at a reception turnstile, subsequent scans within that calendar day return a warning without double-logging attendance. -
Scan Modes (
ScanMode) & Outcomes (scan status):
- CHECK_IN: Logs arrival timestamp at building entrance (CHECK_IN_SUCCESS, or ALREADY_CHECKED_IN if already inside). - CHECK_OUT: Logs departure at exit gate (CHECK_OUT_SUCCESS, or ALREADY_CHECKED_OUT). - CHECK_IN_CHECK_OUT_TOGGLE: Automatically flips status between on-premises and off-premises with each reader scan. - SAVE_ATTENDANCE: Logs repeatable check-in events without toggling entry state.
Contactless NFC Door Access (Apple VAS & Google Smart Tap)
Passinstance supports hardware contactless credential transmission over the ISO/IEC 14443 Type A/B physical layer:
Pass NFC Configuration Dictionary
When configuring contactless door access, the nfc schema is injected into the pass payload:
{
"nfc": {
"message": "FACILITY_ACCESS_NODE_772",
"encryptionPublicKey": "04a1b2c3d4e5f6...",
"requiresAuthentication": true,
"nfcFaceIdRequired": true,
"nfcNoBarcode": false
}
}
-
requiresAuthentication/nfcFaceIdRequired: Prompts the user for Face ID, Touch ID, or passcode verification before the NFC payload is transmitted to the door reader terminal. -
nfcNoBarcode: Suppresses optical barcode display on the pass face when deploying NFC-exclusive secure turnstiles. -
Compatible Hardware Readers: Integrates with certified NFC, Identiv, and HID readers paired with Passinstance via
hardware reader/reader deviceconfigurations.
Instant Offboarding & Revocation API
When an employee departs the organization or a temporary contractor badge expires, access must be revoked immediately:
Revocation Endpoint
/api/v1/passes/voiding/:id/void
{
"voided": true,
"options": {
"reason": "CANCELLED",
"customReason": "EMPLOYEE_OFFBOARDED",
"sendPushNotification": false
}
}
Result
-
1
Pass
statustransitions toVOIDED,lifecycleStatus(PassLifecycleStatus) transitions toVOIDED, and the endpoint returns HTTP204 No Content. Noteoptions.reasonacceptsVoidingReason(EXPIRED,CANCELLED,LOST,STOLEN,DUPLICATE,FRAUD,TECHNICAL_ISSUE,CUSTOMER_REQUEST,ADMIN_ACTION,SYSTEM_AUTO,OTHER). -
2
All subsequent scans at door turnstiles or mobile scanner checkpoints are rejected with decision
ALREADY_VOIDED. -
3
Passinstance updates
walletVoidStatus(WalletPropagationStatus:NONE->PENDING->QUEUED->SUCCEEDED) as background workers push the update via APNs HTTP/2 and Google Wallet REST API.
Important: Contactless Apple Wallet door access requires an approved Apple VAS (Value Added Services) merchant certificate from Apple Developer Relations. Optical QR/Aztec scanning works instantly out-of-the-box on standard cameras and 2D barcode hardware.
Learn more about our Access & Identity Solutions.
