REST API Reference & SDKs

Passinstance Developer Documentation

Build high-volume Apple Wallet (.pkpass) and Google Wallet integrations. Issue, update, scan, and broadcast real-time lockscreen notifications via production-grade REST APIs.

Get API Keys

Developer Docs/reference

REST API v1

All API Reference Passes Templates Scanner & Devices Push & Delivery Webhooks Batch Operations

Security

Authentication & Environment Keys

All API calls require authentication via secret API keys passed in the Authorization header. Never expose secret API keys in client-side mobile apps or browser code.

Production Keys (Live)

Authorization: Bearer pi_live_xxxxxxxxxxxxxxxxxxxxxxxx

Sandbox Keys (Test)

Authorization: Bearer pi_test_xxxxxxxxxxxxxxxxxxxxxxxx

Hardware Scanner Keys

x-scanner-key: scan_key_77a8b9c0d1e2f3a4...

Security Invariant

Server-to-server calls only. Disallow frontend bundle inclusion.

Operations

Error Handling & Rate Limits

Every API response uses the canonical ApiResponseDto envelope. Client errors (4xx) should be fixed before retrying; server errors (5xx) and rate limits (429) should be retried with exponential backoff.

200 OK / 201 Created

{ "success": true, "data": { ... }, "errors": [], "statusCode": 200 }

400 Bad Request

{ "success": false, "data": null, "errors": ["Validation failed"], "statusCode": 400 }

409 Conflict

{ "success": false, "data": null, "errors": ["Serial number already exists"], "statusCode": 409 }

429 Rate Limited

100 req/sec limit. Check Retry-After response header before retrying.

Resources

Official SDKs & Client Libraries

Official thin SDKs providing end-to-end TypeScript interfaces, automatic token caching, exponential backoff retries, and cryptographic webhook signature validation.

Node.js / TypeScript

npm install @passinstance/node

Python (3.9+)

pip install passinstance

PHP (8.1+)

composer require passinstance/passinstance-php

POST/passes

Passes

Request

curl -X POST https://api.passinstance.com/api/v1/passes \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -d '{
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "name": "Acme VIP Customer Pass",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z"
  }'

Response

CreatedApiResponseDto<Pass> with passAccessUrl and downloadUrl.

{
  "success": true,
  "data": {
    "id": "pass_9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "templateId": "tpl_8f2a1e0b-3c4d-4e5f-9a1b-2c3d4e5f6a7b",
    "serialNumber": "MEMBER-2024-8891",
    "name": "Acme VIP Customer Pass",
    "organizationName": "Acme Rewards",
    "backgroundColor": "#1b2d3c",
    "foregroundColor": "#ffffff",
    "labelColor": "#7db4f0",
    "barcode": {
      "value": "PI-8891-JD-VIP",
      "alternativeText": "8891-VIP"
    },
    "images": {
      "icon": "https://assets.passinstance.com/media/icon.png",
      "logo": "https://assets.passinstance.com/media/logo.png",
      "strip": "https://assets.passinstance.com/media/strip.png"
    },
    "relevantDate": "2026-08-25T18:00:00.000Z",
    "status": "ACTIVE",
    "voided": false,
    "downloadUrl": "https://passinstance.com/p/pass_9a8b7c6d",
    "passAccessUrl": "https://passinstance.com/p/pass_9a8b7c6d",
    "createdAt": "2026-08-21T20:30:00.000Z",
    "updatedAt": "2026-08-21T20:30:00.000Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Envelope: ApiResponseDto<T>HTTPS (TLS 1.3)