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_...orpi_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/:tokenor/d/:slug) to end-user devices.
Base URLs & Interactive OpenAPI Documentation
| Resource / Environment | URL | Description |
|---|---|---|
| Production API Base URL | https://api.passinstance.com/api/v1 | Live workspace issuance, wallet push updates, and production scanning. |
| Staging / Sandbox Base URL | https://staging-api.passinstance.com/api/v1 | Isolated pre-production testing environment. |
| Public Interactive Swagger UI | GET https://api.passinstance.com/api/public/docs | Filtered OpenAPI 3.0 specification for third-party developers across all environments. |
| Full Non-Prod Swagger UI | GET /api/docs | Complete 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):
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 Type | HTTP Header | Token Prefix / Format | Permitted Surface |
|---|---|---|---|
| Production API Key | Authorization: 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 Key | Authorization: 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 Token | Authorization: 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 Key | x-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:
| Method | Endpoint | Required Permission (api-key-permissions) | Description |
|---|---|---|---|
| GET | /api/v1/api-keys | api:keys-read or api:keys-manage | Lists all active (and optional ?includeInactive=true) API keys with masked key values. |
| GET | /api/v1/api-keys/:id | api:keys-read or api:keys-manage | Fetches metadata for a single API key by UUID. |
| POST | /api/v1/api-keys | api:keys-manage | Creates a new pi_live_ or pi_test_ API key (request payload); returns plaintext key once. |
PATCH / PUT | /api/v1/api-keys/:id | api:keys-manage | Updates the key's name, scopes, or expiresAt (request payload). |
| DELETE | /api/v1/api-keys/:id | api:keys-manage | Permanently deletes an API key and records an API_KEY_DELETED audit log entry. |
| POST | /api/v1/api-keys/:id/regenerate | api:keys-manage | Generates a new secret token while preserving the key's id, name, and scopes. |
| POST | /api/v1/api-keys/:id/activate | api:keys-manage | Re-enables a previously deactivated API key immediately. |
| POST | /api/v1/api-keys/:id/deactivate | api:keys-manage | Soft-deactivates an API key (archivedAt timestamp) without losing configuration. |
| POST | /api/v1/api-keys/:id/test | api:keys-manage | Verifies key configuration and validity status (API key verification result). |
| GET | /api/v1/api-keys/:id/usage | api:keys-read or api:keys-manage | Returns 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 (includingexternalIdlookups andbundleId.pkpassdownloads). -
'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)
{
"name": "Shopify Checkout Issuance Worker",
"environment": "live",
"scopes": ["passes", "templates"],
"expiresAt": "2027-11-16T00:00:00.000Z"
}
Response (201 Created):
{
"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.keyis returned only once in the201 Createdor/regenerateresponse. SubsequentGET /api/v1/api-keyscalls return a masked prefix inkey.
Explore the full endpoint catalog in API Reference and interactive specs at /docs.
