Skip to content
Help Center Guide · Pass ScanningOnboarding Phase 4
5 min readVerified 2026-11-16

Scanner Setup & Configuration

Set up Validation Places, create Scanner Configurations (Mobile App or Web Scanner), and install the Passinstance Scanner app.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus1 / 2
Key UI elements

Create Scanner Configuration wizard (Zoomed)

Set a configuration name, description, Mobile App configuration type, and success message duration to generate a secure scanner profile.

Overview

Before cashiers, gate attendants, or retail POS terminals can validate customer wallet passes, you must configure a Validation Place and bind a Scanner Configuration (ScannerConfiguration model) inside your workspace (/scanner and /scanner/configs in the Dashboard). Passinstance manages device pairing, operator PIN enforcement, key rotation, telemetry reporting, and offline snapshot synchronization through Scanner Keys API (/api/v1/scanner-keys), Validation Config API (/api/v1/validation), and Scan Validation API (/api/v1/scans).

Scanner validation places and configuration controls
Scanner validation places and configuration controls

Prerequisites: You must have an active published Pass Template and workspace permissions to manage validation configurations (validation:manage, or scans:read for key provisioning) before generating pairing links or provisioning raw scanner keys.

Scanner Configuration Types & Core Enums

Passinstance separates native handheld scanning from public browser-based checkpoint links using ScannerConfigurationType:

Enum (ScannerConfigurationType)ChannelAuth MechanismTypical Deployment
SMART_SCAN_APPPassinstance Scanner app (iOS / Android) & integrated POS SDKsPaired x-scanner-key (from-link or for-config)Gate check-in handhelds, offline venues, retail cash registers.
VALIDATION_LINKWeb browser checkpoint (/api/v1/public/validation/:configId/validate)Signed web validation linkPopup event desks or partner booths without app installation.

Step-by-Step Setup

  1. 1
    Define Validation Places: Create physical or logical checkpoints (e.g., Main Entrance, Register 1, VIP Lounge) to segment scan analytics and restrict which passes can be redeemed at each location (validValidationPlaces).
  2. 2
    Create a Scanner Configuration: In Scanner -> Scanner Configurations (/scanner/configs), define the profile name, type (ScannerConfigurationType), allowed templates (templateId / allowedTemplates), ScanMode, StoredValueOperation (NONE | ADD | SUBTRACT | SET), StoredValueAmountSource (FIXED | OPERATOR | MECHANIC), operator PIN (unlockPinHash), and whether staff can switch profiles in-flight (allowChangesViaLink: true).
  3. 3
    Pair the Device or Provision a Key:

- Mobile App (SMART_SCAN_APP): Scan a QR pairing link (ScannerAccessLink) or enter an access token to exchange it via POST /api/v1/scanner-keys/from-link. - Authenticated App / POS Terminal: After user login + profile selection, issue a dedicated key directly via POST /api/v1/scanner-keys/for-config.

  1. 4
    Verify Heartbeat & Offline Sync: The scanner app verifies key health via GET /api/v1/scanner-keys/verify, queues failed offline submissions up to MAX_RETRY_ATTEMPTS = 3 with client-generated x-idempotency-key headers, and caches pass snapshots via GET /api/v1/scans/offline-dataset.

Architecture & Device Pairing Lifecycle

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SCANNER DEVICE PAIRING & TELEMETRY SYNC
PARTICIPATING SYSTEM ACTORS
P1 Scanner Device / App
P2 Scanner Keys API
P3 Scan Validation API
STEP 1 REQUEST / ACTION POST/scanner-keys/
›
from-link {token, pin?}
STEP 2 RESPONSE 201 Created
›
{ scannerKey,
›
alidationConfig,
›
key: "sk_live_..." }
STEP 3 REQUEST / ACTION GET/scanner-keys/verify
›
Headers: x-scanner-key,
›
x-scanner-battery-level,
›
x-scanner-queue-backlog
STEP 4 RESPONSE 200 OK { shouldRotate }
STEP 5 REQUEST / ACTION GET/scans/offline-dataset ?cursor=...&limit=500
STEP 6 RESPONSE 200 OK { items, nextCursor, snapshotAt }

Scanner Key Lifecycle Endpoints (Scanner Keys API)

All device key provisioning, profile switching, PIN verification, and rotation operations are exposed under /api/v1/scanner-keys:

MethodEndpointAuth / GuardDescription
POST/api/v1/scanner-keys/from-linkPublic (ScannerAccessLink, CSRF-exempt)Exchanges { token, pin? } for a persistent x-scanner-key (key, returned once).
POST/api/v1/scanner-keys/for-configWorkspace JWT (scans:read)Issues a new scanner key for a tenant-owned { configId }.
GET/api/v1/scanner-keys/configsx-scanner-keyLists active SMART_SCAN_APP configurations bound to the calling key's tenant.
POST/api/v1/scanner-keys/switchx-scanner-keySwitches the key to another { configId, pin? } when allowChangesViaLink: true.
POST/api/v1/scanner-keys/unlock-pinx-scanner-keyVerifies { pin } against unlockPinHash with automatic brute-force lockout protection.
GET/api/v1/scanner-keys/verifyx-scanner-keyValidates key status, records device telemetry headers, and returns shouldRotate advisory.
POST/api/v1/scanner-keys/revokex-scanner-keyImmediately revokes the calling scanner key, blocking all subsequent scan submissions.
POST/api/v1/scanner-keys/:id/rotateWorkspace JWT (scans:read)Atomically rotates an existing scanner key by ID and returns a new raw secret key once.

1. Pairing via Access Link (POST /api/v1/scanner-keys/from-link)

When staff scan a setup QR code in the Passinstance Scanner app, the device exchanges the setup token (and optional operator PIN if unlockPinHash is configured) for a persistent x-scanner-key:

JSON
{
  "token": "sal_9f82b1c4e7a043d19b2e",
  "pin": "4829"
}

Response (201 Created):

JSON
{
  "scannerKey": {
    "id": "skey_01hxyz8912ab",
    "createdAt": "2026-11-16T09:00:00.000Z",
    "expiresAt": "2027-02-15T00:00:00.000Z"
  },
  "validationConfig": {
    "id": "scfg_main_entrance_01",
    "configurationId": "MAIN_ENTRANCE",
    "name": "Main Entrance Gate",
    "scanMode": "CHECK_IN",
    "type": "SMART_SCAN_APP",
    "place": "Main Entrance",
    "isActive": true,
    "allowChangesViaLink": true,
    "templateId": "tmpl_event_vip",
    "allowedTemplateIds": ["tmpl_event_vip"],
    "version": 3
  },
  "key": "sk_live_7d9a2f4b8c1e6039a5d2e8f1"
}

Important: The key value is returned only once at creation or rotation time and stored as a SHA-256 hash (hashKey) in the database. Store key securely in the device keychain; if lost, invoke POST /api/v1/scanner-keys/:id/rotate.

2. Heartbeat, Telemetry & Rotation Advisory (GET /api/v1/scanner-keys/verify)

Scanner clients periodically call GET /api/v1/scanner-keys/verify with x-scanner-key and operational telemetry headers so administrators can monitor fleet health in real time:

Telemetry HeaderFormat / ExamplePurpose
x-scanner-app-version2.4.1 (build 108)Tracks app build version across deployed handhelds.
x-scanner-device-idios-idfv-8841-992aUnique hardware identifier for device fleet inventory.
x-scanner-battery-level0.78 (0–1 or 0–100)Alerts operations staff when gate scanners drop below 15% charge.
x-scanner-queue-backlog12Number of offline scans queued locally awaiting upload sync.

Response (200 OK):

JSON
{
  "valid": true,
  "scannerKeyId": "skey_01hxyz8912ab",
  "scannerConfigurationId": "scfg_main_entrance_01",
  "validationConfigId": "scfg_main_entrance_01",
  "expiresAt": "2026-11-25T12:00:00.000Z",
  "daysUntilExpiration": 9,
  "shouldRotate": true,
  "message": "Scanner key is approaching expiration. Please rotate soon."
}

When daysUntilExpiration < 15, shouldRotate evaluates to true, prompting the device or administrator to rotate the credential via POST /api/v1/scanner-keys/:id/rotate.

3. In-Flight Profile Switching (POST /api/v1/scanner-keys/switch)

If a configuration has allowChangesViaLink: true, staff can switch a single handheld scanner between different SMART_SCAN_APP profiles (for example, moving from Door Check-In to VIP Merchandise Redemption) without re-pairing:

JSON
{
  "configId": "scfg_vip_merch_02",
  "pin": "9012"
}

If the target configuration requires an operator PIN, the server validates pin against unlockPinHash before rebinding the key. Operators can also validate their PIN standalone via POST /api/v1/scanner-keys/unlock-pin.

Offline Dataset Synchronization (GET /api/v1/scans/offline-dataset)

For venues with intermittent cellular or Wi-Fi connectivity, mobile scanners synchronize a compact, key-scoped pass snapshot (offline scan dataset) via GET /api/v1/scans/offline-dataset.

Query Parameters

  • cursor (optional string): Pagination cursor returned by the previous page (nextCursor).
  • limit (optional number): Maximum records per page.
  • snapshotAt (optional ISO 8601 timestamp): Incremental delta sync timestamp to fetch only passes created, updated, or voided since the last snapshot.

Example Request & Snapshot Pass Item (IOfflineDatasetPassResponse)

GET /api/v1/scans/offline-dataset?limit=500&snapshotAt=2026-11-16T08:00:00.000Z
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "config": {
    "id": "scfg_main_entrance_01",
    "customerTimezone": "Europe/Berlin",
    "scanMode": "CHECK_IN",
    "validValidationPlaces": ["Main Entrance"]
  },
  "snapshotAt": "2026-11-16T09:00:00.000Z",
  "nextCursor": "pass_01hxyz9940",
  "hasMore": true,
  "items": [
    {
      "id": "pass_01hxyz9939",
      "templateId": "tmpl_event_vip",
      "serialNumber": "PI-VIP-00419",
      "externalId": "crm_attendee_9012",
      "barcodeValue": "PI-VIP-00419",
      "status": "ACTIVE",
      "voided": false,
      "expirationDate": "2026-12-31T23:59:59.000Z",
      "storedValue": "50.00",
      "mechanicType": "NONE",
      "lastSuccessfulScanAt": "2026-11-15T19:04:00.000Z",
      "validationPlaces": ["Main Entrance"]
    }
  ]
}

Explore hardware compatibility and validation workflows on the Scanner Product Page and Scan Modes & Validation Rules.

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.