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.0.0

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.

Templates

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

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.

Operate the pass lifecycle

PUT /passes/{id}

Update pass fields, void stale passes, and rely on wallet update delivery.

Connect backend events

POST /webhooks

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.

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 17 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

17 of 17 operations shown

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

Passes

6 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

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

Templates

3 operations

GET/templates

Get all templates

Auth

POST/templates

Create a new template

Auth

GET/templates/{id}

Get a specific template

Auth

Webhooks

2 operations

GET/webhooks

Get all webhooks

Auth

POST/webhooks

Create a webhook

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