Skip to content
Help Center Guide · Developer API
4 min readVerified 2026-11-16

API Overview & Authentication

Understand base URLs (api.passinstance.com/api/v1), API Keys vs. scoped Scanner/SDK tokens, headers, and rate limits.

In This Guide

Overview

The Passinstance REST API enables server-to-server pass issuance, template management, real-time balance mutations, webhook orchestration, and analytics extraction. All standard endpoints are mounted under the versioned base path https://api.passinstance.com/api/v1, accept and return UTF-8 JSON (Content-Type: application/json), and wrap standard responses in a deterministic API response (T) envelope.

Important: Never embed workspace API keys (pi_live_... or pi_test_...) inside client-side browser JavaScript, mobile application binaries, or public Git repositories. Always call the Passinstance API from your backend server and pass only the resulting smart download URL (/s/:token or /d/:slug) to end-user devices.

Base URLs & Interactive OpenAPI Documentation

Resource / EnvironmentURLDescription
Production API Base URLhttps://api.passinstance.com/api/v1Live workspace issuance, wallet push updates, and production scanning.
Staging / Sandbox Base URLhttps://staging-api.passinstance.com/api/v1Isolated pre-production testing environment.
Public Interactive Swagger UIGET https://api.passinstance.com/api/public/docsFiltered OpenAPI 3.0 specification for third-party developers across all environments.
Full Non-Prod Swagger UIGET /api/docsComplete internal Swagger UI generated in non-production environments (also embedded at /settings/workspace/developer in the Dashboard).

Authentication Architecture & Environment Rules

Passinstance enforces strict blast-radius separation across three credential families (API Key Authentication, OAuth 2.0 Authentication, and Scanner Key Authentication):

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
API AUTHENTICATION & SCOPE VERIFICATION
PARTICIPATING SYSTEM ACTORS
P1 Client / Backend Server
P2 API Gateway & Auth Guards
P3 Target Controller
STEP 1a REQUEST / ACTION Authorization: ApiKey
›
(API Key Authentication)
›
pi_live_...
›
Verify key hash, expiry
›
& environment (test vs live)
›
Check API_KEY_SCOPE_VALUES
›
(passes, templates, scans,
STEP 1b REQUEST / ACTION x-api-key: pi_live_...
›
webhooks, analytics, *)
STEP 1c REQUEST / ACTION x-scanner-key: <key>
›
(Scanner Key Authentication)
›
Restrict to /api/v1/scans
›
& /api/v1/scanner-keys
STEP 2 REQUEST / ACTION Enforce Tenant Isolation
STEP 3 RESPONSE 200 OK API response (T) --
›
<-------------------------------

Supported Authentication Headers & API_KEY_ENVIRONMENT_VALUES

request payload.environment uses API_KEY_ENVIRONMENT_VALUES ('test' | 'live'). Sandbox keys (pi_test_...) are valid only on sandbox workspaces, whereas live keys (pi_live_...) are valid only on production workspaces:

Credential TypeHTTP HeaderToken Prefix / FormatPermitted Surface
Production API KeyAuthorization: ApiKey pi_live_... or x-api-key: pi_live_...pi_live_<secret> (environment: "live")Production workspace API calls matching assigned API_KEY_SCOPE_VALUES.
Sandbox API KeyAuthorization: ApiKey pi_test_... or x-api-key: pi_test_...pi_test_<secret> (environment: "test")Sandbox workspace testing and automated CI/CD integration suites.
OAuth 2.0 Bearer TokenAuthorization: Bearer <jwt>Signed JWT (OAuth 2.0 Authentication + Permission Scope Validation)Connected iPaaS platforms (Zapier, Make) using granular OAuth scopes (webhooks:read, webhooks:write, templates:read).
Scanner Device Keyx-scanner-key: <scanner-key><scanner-key> (Scanner Key Authentication)Strictly isolated to /api/v1/scans, /api/v1/scanner-keys, and mechanic scan routes.

API Key Management (API Keys API & Dashboard UI)

Manage credentials visually in Workspace Settings -> Developer -> API Credentials (/settings/workspace/developer/api-credentials, or /platform/api-keys) or programmatically via /api/v1/api-keys:

MethodEndpointRequired Permission (api-key-permissions)Description
GET/api/v1/api-keysapi:keys-read or api:keys-manageLists all active (and optional ?includeInactive=true) API keys with masked key values.
GET/api/v1/api-keys/:idapi:keys-read or api:keys-manageFetches metadata for a single API key by UUID.
POST/api/v1/api-keysapi:keys-manageCreates a new pi_live_ or pi_test_ API key (request payload); returns plaintext key once.
PATCH / PUT/api/v1/api-keys/:idapi:keys-manageUpdates the key's name, scopes, or expiresAt (request payload).
DELETE/api/v1/api-keys/:idapi:keys-managePermanently deletes an API key and records an API_KEY_DELETED audit log entry.
POST/api/v1/api-keys/:id/regenerateapi:keys-manageGenerates a new secret token while preserving the key's id, name, and scopes.
POST/api/v1/api-keys/:id/activateapi:keys-manageRe-enables a previously deactivated API key immediately.
POST/api/v1/api-keys/:id/deactivateapi:keys-manageSoft-deactivates an API key (archivedAt timestamp) without losing configuration.
POST/api/v1/api-keys/:id/testapi:keys-manageVerifies key configuration and validity status (API key verification result).
GET/api/v1/api-keys/:id/usageapi:keys-read or api:keys-manageReturns request telemetry, latency averages, and HTTP status-code breakdown (API key usage summary).

Available API Key Scopes (API_KEY_SCOPE_VALUES)

Follow the principle of least privilege by assigning only the scopes required by each backend worker (defaults to ["*"] if omitted):

  • 'passes' — Issue, inspect, update, void, and search pass instances (including externalId lookups and bundleId .pkpass downloads).
  • 'templates' — Read template schemas, custom attributes, and mechanics.
  • 'scans' — Execute validations, inspect scan results, and trigger mechanics.
  • 'webhooks' — Manage webhook subscriptions and poll pull-webhook queues.
  • 'analytics' — Query pass issuance, device registration, and wallet share metrics.
  • '*' — Full administrative access across all developer API domains.

Creating a Scoped API Key (POST /api/v1/api-keys)

JSON
{
  "name": "Shopify Checkout Issuance Worker",
  "environment": "live",
  "scopes": ["passes", "templates"],
  "expiresAt": "2027-11-16T00:00:00.000Z"
}

Response (201 Created):

JSON
{
  "success": true,
  "data": {
    "id": "2c668b45-2b28-4c65-b17d-a6c7272e27ea",
    "name": "Shopify Checkout Issuance Worker",
    "key": "pi_live_89a1f4c2e90b41d7a6c3e2f10984b2c1",
    "keyPrefix": "pi_live_",
    "environment": "live",
    "scopes": ["passes", "templates"],
    "customerId": "89a12b34-56c7-4d89-9e01-23456789abcd",
    "isActive": true,
    "expiresAt": "2027-11-16T00:00:00.000Z",
    "createdAt": "2026-11-16T10:00:00.000Z"
  },
  "description": "API key created successfully",
  "errors": [],
  "statusCode": 201
}

Important: The unhashed secret data.key is returned only once in the 201 Created or /regenerate response. Subsequent GET /api/v1/api-keys calls return a masked prefix in key.

Explore the full endpoint catalog in API Reference and interactive specs at /docs.

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.