Production API guide

Build Apple Wallet and Google Wallet passes against the production API.

A cleaner developer portal for the Passinstance REST API: versioned routes, secure auth, webhooks, and an OpenAPI-powered reference for production wallet pass workflows.

Start quickstart View reference Dashboard usage guide

OpenAPI

1.1.1

Endpoints

Response format

JSON

Production base URL

PRODUCTION_BASE_URL=https://api.passinstance.com/api/v1
STAGING_BASE_URL=https://staging-api.passinstance.com/api/v1

Create a pass

curl --request POST \
  --url https://api.passinstance.com/api/v1/passes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "templateId": "tpl_abcdef1234567890",
    "serialNumber": "ORDER-1001",
    "fields": {
      "memberName": { "label": "Member", "value": "Jane Doe" },
      "tier": { "label": "Tier", "value": "Gold" }
    },
    "barcodeFormat": "qr",
    "barcodeMessage": "ORDER-1001-GOLD"
  }'

Versioned base path

/api/v1

Public integrations use stable, versioned resource routes.

Auth modes

Bearer or API key

Send credentials only from trusted server-side environments.

Abuse protection

Rate limited

Clients should back off when retry guidance is returned.

Availability

Monitored

Use dashboard and support channels for operational status.

API surface

Core workflows covered by the public REST API

The reference is generated from the bundled OpenAPI spec and grouped by the same resources exposed by the API project.

Pass lifecycle

Create, update, void, delete, and download wallet passes.

Wallet downloads

Serve Apple .pkpass files and Google Wallet save links.

Templates

Keep wallet structure, branding, pass type, and colors reusable.

Scans

Process barcode scans and look up pass state from scanner devices.

Pass mechanics

Stamp, debit, redeem, and read ledger state for loyalty programs.

API keys

Create, rotate, and monitor server-side integration credentials.

Webhooks

Subscribe downstream systems to pass and template events.

Notifications

Trigger wallet updates and customer-facing pass notifications.

Bundles

Group related passes for campaign, order, or event workflows.

Batch jobs

Run high-volume pass operations and poll job state.

Quickstart

The shortest production path

Use the dashboard for credentials and certificates, then automate pass issuance and updates through the API.

Create or select a template

POST /templates

Define the pass type, organization fields, colors, and wallet identity once.

Issue passes from the template

POST /passes

Send customer-specific fields, barcode payloads, relevant dates, and expiry.

Hand customers install links

GET /passes/{id}/download-urls

Return Apple Wallet, Google Wallet, and download-page URLs from your backend.

Operate scans and mechanics

POST /scans · POST /passes/{id}/use

Process scanner scans with x-scanner-key, or apply stamp/debit/redeem actions.

Connect backend events

POST /webhooks/subscriptions

Create a pass with Node.js

const response = await fetch("https://api.passinstance.com/api/v1/passes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PASSINSTANCE_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    templateId: "tpl_abcdef1234567890",
    serialNumber: "ORDER-1001",
    fields: {
      memberName: { label: "Member", value: "Jane Doe" },
      tier: { label: "Tier", value: "Gold" },
    },
    barcodeFormat: "qr",
    barcodeMessage: "ORDER-1001-GOLD",
  }),
});

if (!response.ok) {
  throw new Error(`Pass creation failed: ${response.status}`);
}

const pass = await response.json();

Create a pass with Python

import os
import requests

response = requests.post(
    "https://api.passinstance.com/api/v1/passes",
    headers={
        "Authorization": f"Bearer {os.environ['PASSINSTANCE_TOKEN']}",
        "Content-Type": "application/json",
    },
    json={
        "templateId": "tpl_abcdef1234567890",
        "serialNumber": "ORDER-1001",
        "fields": {
            "memberName": {"label": "Member", "value": "Jane Doe"},
            "tier": {"label": "Tier", "value": "Gold"},
        },
        "barcodeFormat": "qr",
        "barcodeMessage": "ORDER-1001-GOLD",
    },
    timeout=15,
)
response.raise_for_status()
pass_object = response.json()

Keep tokens and API keys in your server environment. Browser clients should call your backend, not the Passinstance API directly.

Authentication

Secure server-side integrations

The API supports bearer authentication and API-key authentication. Keep secrets in your backend, send JSON bodies, and expose only wallet download links or PassFlow URLs to client devices.

Bearer token

Use for user-context operations from trusted backend services.

Header

Authorization: Bearer <access_token>

API key

Use for service-to-service connectors where a stable integration identity is needed.

Header

X-API-Key: <api_key>

Webhooks

Push pass events into your systems

Configure a receiver URL, subscribe to pass and template events, verify signatures, and return a successful response only after the event is safely queued or processed.

pass.created
pass.updated
pass.voided
template.created

curl --request POST \
  --url https://api.passinstance.com/api/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-app.example/webhooks/passinstance",
    "events": ["pass.created", "pass.updated", "pass.voided"],
    "secret": "<webhook_secret>"
  }'

Production readiness

Operational behavior to design for

Design clients that keep credentials private, handle validation errors cleanly, retry conservatively, and process duplicate webhook deliveries safely.

Use HTTPS endpoints and keep API keys server-side only.

Send x-scanner-key only from trusted scanner devices or backends.

Handle 401, 403, 404, 422, 429, and 5xx responses explicitly.

Respect documented retry guidance before sending follow-up requests.

Generate stable serial numbers and keep idempotency keys in your own system.

Store webhook event ids and process duplicate deliveries safely.

Use staging before switching clients to the production base URL.

429 response pattern

HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>

{
  "error": "Too Many Requests",
  "message": "Retry after the indicated delay"
}

Retry policy

if (response.status === 429 || response.status >= 500) {
  wait(response.headers.get("Retry-After") ?? nextBackoffDelay())
  retryRequest()
}

Reference

OpenAPI endpoint catalogue

Passinstance API exposes 48 documented operations. Copy the base URL once, then append the resource path shown below.

Production

https://api.passinstance.com/api/v1

Staging

https://staging-api.passinstance.com/api/v1

Search the API reference

48 of 48 operations shown

API Keys

7 operations

GET/api-keys

List API keys

Auth

POST/api-keys

Create an API key

Auth

DELETE/api-keys/{id}

Delete an API key

Auth

GET/api-keys/{id}

Get an API key

Auth

POST/api-keys/{id}/rotate

Rotate an API key

Auth

GET/api-keys/{id}/usage

Get API key usage

Auth

POST/api-keys/rotate-all

Rotate all API keys

Auth

Batch Operations

2 operations

POST/batch

Create batch operation

Auth

GET/batch/{id}

Get batch operation status

Auth

Bundles

2 operations

GET/bundles

Get all bundles

Auth

POST/bundles

Create a bundle

Auth

Pass Mechanics

4 operations

GET/mechanics/{mechanicId}/passes/{passId}/ledger

Get mechanic ledger for a pass

Auth

GET/mechanics/{mechanicId}/passes/{passId}/state

Get mechanic state for a pass

Auth

POST/mechanics/redeem

Redeem a mechanic reward

Auth

POST/passes/{id}/use

Apply a mechanic action to a pass

Auth

Passes

7 operations

GET/passes

Get all passes

Auth

POST/passes

Create a new pass

Auth

DELETE/passes/{id}

Delete a pass

Auth

GET/passes/{id}

Get a specific pass

Auth

PATCH/passes/{id}

Partially update a pass

Auth

PUT/passes/{id}

Update a pass

Auth

POST/passes/{id}/void

Void a pass

Auth

Push Notifications

2 operations

GET/push-notifications

Get all notifications

Auth

POST/push-notifications

Send a push notification

Auth

Scans

3 operations

POST/scans

Process a barcode scan

Auth

GET/scans/offline-dataset

Fetch offline scan dataset

Auth

GET/scans/pass/{barcodeValue}

Look up pass state by barcode

Auth

Templates

5 operations

GET/templates

Get all templates

Auth

POST/templates

Create a new template

Auth

GET/templates/{id}

Get a specific template

Auth

PATCH/templates/{id}

Partially update a template

Auth

PUT/templates/{id}

Replace a template

Auth

Wallet Downloads

3 operations

GET/passes/{id}/download

Download Apple Wallet pass (.pkpass)

Auth

GET/passes/{id}/download-urls

Get wallet install URLs

Auth

GET/passes/{id}/google-wallet-link

Get Google Wallet save link

Auth

Webhooks

13 operations

GET/webhooks

Get all webhooks

Auth

POST/webhooks

Create a webhook

Auth

POST/webhooks/fire-test-event

Fire a test event to matching subscriptions

Auth

GET/webhooks/history

Get webhook delivery history

Auth

DELETE/webhooks/inbox

Clear webhook test inbox

Auth

GET/webhooks/inbox

Get webhook test inbox

Auth

POST/webhooks/subscribe

Subscribe to webhook events

Auth

GET/webhooks/subscriptions

List webhook subscriptions

Auth

POST/webhooks/subscriptions

Create a webhook subscription

Auth

DELETE/webhooks/subscriptions/{id}

Delete a webhook subscription

Auth

POST/webhooks/subscriptions/{id}/test

Send a test delivery to a subscription

Auth

POST/webhooks/unsubscribe

Unsubscribe from webhook events

Auth

POST/webhooks/verify-signature

Verify a webhook signature

Auth

Ready to build against the production API?

Start with staging credentials, validate one pass end to end, then enable production credentials and webhook receivers for your rollout.

Get API access Talk to engineering