Skip to content
Help Center Guide
3 min readVerified 2026-11-16

Employee IDs & Access Passes

Issue staff, contractor, and visitor credentials with expiry dates, optical 2D check-in, and instant revocation.

In This Guide

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:

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
EMPLOYEE ACCESS & REVOCATION
PARTICIPATING SYSTEM ACTORS
P1 HR System / REST API
P2 Passinstance Core API
P3 Door Reader / Scanner
P4 Mobile Wallet Pass
STEP 1 REQUEST / ACTION POST/api/v1/passes
STEP 2 REQUEST / ACTION Provision Pass & NFC
STEP 3 REQUEST / ACTION Add to Wallet
›
(Photo ID + Biometrics)
STEP 4 RESPONSE Tap Reader
STEP 5 RESPONSE POST/api/v1/scans
›
(NFC ISO 14443 / QR)
›
(Verify ACTIVE & shift)
STEP 6 REQUEST / ACTION Access Granted (200)
STEP 7 REQUEST / ACTION POST/api/v1/passes/voiding/:id/void
STEP 8 REQUEST / ACTION Silent APNs Push
›
(walletVoidStatus)
›
(Turnstile rejects
›
subsequent scans)

Visual Layout & Asset Slots

  • Pass Type (pass type): studentId, generic, or posterGeneric (Apple Wallet and Google Wallet present these with dedicated identity card proportions).
  • HRIS & Directory Correlation (externalId): Store your directory/HR employee ID in externalId (max 255 chars, unique across live tenant passes) so automated offboarding webhooks can void or update passes via POST /api/v1/passes/upsert-by-external-id or GET /api/v1/passes/by-external-id/:externalId.
  • Catalog Demo Templates: student-id-card, daily-access-pass, and conference-badge.
  • Photo Identification: Upload staff portrait photos to the thumbnail asset slot (90x90 pt at @1x, 270x270 px at @3x). Google Wallet renders this as a prominent circular or square avatar.
  • Organization Branding: Fixed logo and strip banner 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): The Pass Mechanics Engine resolves 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:

JSON
{
  "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 device configurations.

Instant Offboarding & Revocation API

When an employee departs the organization or a temporary contractor badge expires, access must be revoked immediately:

Revocation Endpoint

POST /api/v1/passes/voiding/:id/void
Headers
X-API-Key <API_KEY>
Content-Type application/json
JSON
{
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "EMPLOYEE_OFFBOARDED",
    "sendPushNotification": false
  }
}

Result

  1. 1
    Pass status transitions to VOIDED, lifecycleStatus (PassLifecycleStatus) transitions to VOIDED, and the endpoint returns HTTP 204 No Content. Note options.reason accepts VoidingReason (EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER).
  2. 2
    All subsequent scans at door turnstiles or mobile scanner checkpoints are rejected with decision ALREADY_VOIDED.
  3. 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.

Related Product & Developer Documentation

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.