Überblick
Die Passinstance REST API ermöglicht die Server-to-Server-Passausgabe, Vorlagenverwaltung, Guthabenänderungen in Echtzeit, Webhook-Orchestrierung und Analyse-Extraktion. Alle Standard-Endpunkte sind unter dem versionierten Basispfad https://api.passinstance.com/api/v1 eingebunden, akzeptieren und liefern UTF-8-JSON (Content-Type: application/json) und verpacken Standardantworten in einen deterministischen API response (T)-Umschlag.
Wichtig: Betten Sie Arbeitsbereich-API-Schlüssel (
pi_live_...oderpi_test_...) niemals in clientseitiges Browser-JavaScript, mobile App-Binaries oder öffentliche Git-Repositories ein. Rufen Sie die Passinstance API stets von Ihrem Backend-Server aus auf und geben Sie nur die resultierende Smart-Download-URL (/s/:tokenoder/d/:slug) an Endgeräte weiter.
Basis-URLs & Interaktive OpenAPI-Dokumentation
| Ressource / Umgebung | URL | Beschreibung |
|---|---|---|
| Produktions-API-Basis-URL | https://api.passinstance.com/api/v1 | Produktive Arbeitsbereich-Ausgabe, Wallet-Push-Updates und Produktiv-Scans. |
| Staging- / Sandbox-Basis-URL | https://staging-api.passinstance.com/api/v1 | Isolierte Testumgebung vor dem Produktivgang. |
| Öffentliche interaktive Swagger UI | GET https://api.passinstance.com/api/public/docs | Gefilterte OpenAPI-3.0-Spezifikation für Drittentwickler über alle Umgebungen hinweg. |
| Vollständige Non-Prod-Swagger UI | GET /api/docs | Vollständige interne Swagger UI für Nicht-Produktionsumgebungen (ebenfalls unter /settings/workspace/developer im Dashboard eingebettet). |
Authentifizierungsarchitektur & Umgebungsregeln
Passinstance erzwingt eine strikte Trennung des Wirkungsbereichs über drei Zugangsdaten-Familien (API Key Authentication, OAuth 2.0 Authentication und Scanner Key Authentication):
Unterstützte Authentifizierungs-Header & API_KEY_ENVIRONMENT_VALUES
request payload.environment verwendet API_KEY_ENVIRONMENT_VALUES ('test' | 'live'). Sandbox-Schlüssel (pi_test_...) sind ausschließlich für Sandbox-Arbeitsbereiche gültig, während Live-Schlüssel (pi_live_...) ausschließlich für Produktions-Arbeitsbereiche gültig sind:
| Zugangsdatentyp | HTTP-Header | Token-Präfix / Format | Zulässige Oberfläche |
|---|---|---|---|
| Produktions-API-Schlüssel | Authorization: ApiKey pi_live_... oder x-api-key: pi_live_... | pi_live_<secret> (environment: "live") | Produktions-Arbeitsbereich-API-Aufrufe gemäß zugewiesener API_KEY_SCOPE_VALUES. |
| Sandbox-API-Schlüssel | Authorization: ApiKey pi_test_... oder x-api-key: pi_test_... | pi_test_<secret> (environment: "test") | Sandbox-Arbeitsbereich-Tests und automatisierte CI/CD-Integrationstests. |
| OAuth-2.0-Bearer-Token | Authorization: Bearer <jwt> | Signiertes JWT (OAuth 2.0 Authentication + Permission Scope Validation) | Verbundene iPaaS-Plattformen (Zapier, Make) mit granularen OAuth-Scopes (webhooks:read, webhooks:write, templates:read). |
| Scanner-Geräteschlüssel | x-scanner-key: <scanner-key> | <scanner-key> (Scanner Key Authentication) | Strikt isoliert auf /api/v1/scans, /api/v1/scanner-keys und Mechanik-Scan-Routen. |
API-Schlüsselverwaltung (API Keys API & Dashboard-UI)
Verwalten Sie Zugangsdaten visuell unter Arbeitsbereich-Einstellungen -> Entwickler -> API-Zugangsdaten (/settings/workspace/developer/api-credentials oder /platform/api-keys) bzw. programmatisch über /api/v1/api-keys:
| Methode | Endpunkt | Erforderliche Berechtigung (api-key-permissions) | Beschreibung |
|---|---|---|---|
| GET | /api/v1/api-keys | api:keys-read oder api:keys-manage | Listet alle aktiven (sowie optional ?includeInactive=true) API-Schlüssel mit maskierten key-Werten auf. |
| GET | /api/v1/api-keys/:id | api:keys-read oder api:keys-manage | Ruft Metadaten für einen einzelnen API-Schlüssel anhand seiner UUID ab. |
| POST | /api/v1/api-keys | api:keys-manage | Erstellt einen neuen pi_live_- oder pi_test_-API-Schlüssel (request payload); gibt Klartext-key einmalig zurück. |
PATCH / PUT | /api/v1/api-keys/:id | api:keys-manage | Aktualisiert name, scopes oder expiresAt des Schlüssels (request payload). |
| DELETE | /api/v1/api-keys/:id | api:keys-manage | Löscht einen API-Schlüssel dauerhaft und schreibt einen API_KEY_DELETED-Audit-Log-Eintrag. |
| POST | /api/v1/api-keys/:id/regenerate | api:keys-manage | Erzeugt ein neues geheimes Token unter Beibehaltung von id, name und scopes des Schlüssels. |
| POST | /api/v1/api-keys/:id/activate | api:keys-manage | Reaktiviert einen zuvor deaktivierten API-Schlüssel sofort. |
| POST | /api/v1/api-keys/:id/deactivate | api:keys-manage | Deaktiviert einen API-Schlüssel per Soft-Delete (archivedAt-Zeitstempel), ohne die Konfiguration zu verlieren. |
| POST | /api/v1/api-keys/:id/test | api:keys-manage | Prüft Schlüsselkonfiguration und Gültigkeitsstatus (API key verification result). |
| GET | /api/v1/api-keys/:id/usage | api:keys-read oder api:keys-manage | Liefert Anfrage-Telemetrie, durchschnittliche Latenzen und HTTP-Statuscode-Verteilung (API key usage summary). |
Verfügbare API-Schlüssel-Scopes (API_KEY_SCOPE_VALUES)
Folgen Sie dem Prinzip der minimalen Rechtevergabe, indem Sie jedem Backend-Worker nur die tatsächlich benötigten Scopes zuweisen (Standardwert ist ["*"], sofern weggelassen):
-
'passes'— Pass-Instanzen ausstellen, einsehen, aktualisieren, entwerten und durchsuchen (einschließlichexternalId-Abfragen undbundleId-.pkpass-Downloads). -
'templates'— Vorlagenschemas, benutzerdefinierte Attribute und Mechaniken lesen. -
'scans'— Validierungen ausführen, Scan-Ergebnisse prüfen und Mechaniken auslösen. -
'webhooks'— Webhook-Abonnements verwalten und Pull-Webhook-Warteschlangen abrufen. -
'analytics'— Kennzahlen zu Pass-Ausgaben, Geräteregistrierungen und Wallet-Anteilen abfragen. -
'*'— Vollständiger administrativer Zugriff auf alle Entwickler-API-Domänen.
Bereichsbezogenen API-Schlüssel erstellen (POST /api/v1/api-keys)
{
"name": "Shopify Checkout Issuance Worker",
"environment": "live",
"scopes": ["passes", "templates"],
"expiresAt": "2027-11-16T00:00:00.000Z"
}
Antwort (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
}
Wichtig: Das ungehashte Geheimnis
data.keywird nur ein einziges Mal in der201 Created- oder/regenerate-Antwort zurückgegeben. NachfolgendeGET /api/v1/api-keys-Aufrufe liefern ein maskiertes Präfix inkey.
Den vollständigen Endpunkt-Katalog finden Sie in der API-Referenz und interaktive Spezifikationen unter /docs.
