Skip to content
Hilfecenter-Anleitung · Entwickler-API
4 Min. LesezeitGeprüft 2026-11-16

API-Übersicht & Authentifizierung

Basis-URLs (api.passinstance.com/api/v1), API-Schlüssel vs. Scanner/SDK-Tokens, Header und Rate-Limits im Überblick.

In dieser Anleitung

Ü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_... oder pi_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/:token oder /d/:slug) an Endgeräte weiter.

Basis-URLs & Interaktive OpenAPI-Dokumentation

Ressource / UmgebungURLBeschreibung
Produktions-API-Basis-URLhttps://api.passinstance.com/api/v1Produktive Arbeitsbereich-Ausgabe, Wallet-Push-Updates und Produktiv-Scans.
Staging- / Sandbox-Basis-URLhttps://staging-api.passinstance.com/api/v1Isolierte Testumgebung vor dem Produktivgang.
Öffentliche interaktive Swagger UIGET https://api.passinstance.com/api/public/docsGefilterte OpenAPI-3.0-Spezifikation für Drittentwickler über alle Umgebungen hinweg.
Vollständige Non-Prod-Swagger UIGET /api/docsVollstä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):

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
API-AUTHENTIFIZIERUNG & BEREICHSPRÜFUNG
BETEILIGTE SYSTEMKOMPONENTEN
P1 Client / Backend-Server
P2 API-Gateway & Auth Guards
P3 Ziel-Controller
SCHRITT 1a ANFRAGE / AKTION Authorization: ApiKey
›
(API Key Authentication)
›
pi_live_...
›
Schlüssel-Hash, Ablauf
›
& Umgebung (test vs live)
›
API_KEY_SCOPE_VALUES prüfen
›
(passes, templates, scans,
SCHRITT 1b ANFRAGE / AKTION x-api-key: pi_live_...
›
webhooks, analytics, *)
SCHRITT 1c ANFRAGE / AKTION x-scanner-key: <key>
›
(Scanner Key Authentication)
›
Einschränken auf
›
/api/v1/scans &
›
/api/v1/scanner-keys
SCHRITT 2 ANFRAGE / AKTION Mandantenisolation prüfen
SCHRITT 3 ANTWORT 200 OK API response (T) --
›
<-------------------------------

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:

ZugangsdatentypHTTP-HeaderToken-Präfix / FormatZulässige Oberfläche
Produktions-API-SchlüsselAuthorization: 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üsselAuthorization: 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-TokenAuthorization: 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üsselx-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:

MethodeEndpunktErforderliche Berechtigung (api-key-permissions)Beschreibung
GET/api/v1/api-keysapi:keys-read oder api:keys-manageListet alle aktiven (sowie optional ?includeInactive=true) API-Schlüssel mit maskierten key-Werten auf.
GET/api/v1/api-keys/:idapi:keys-read oder api:keys-manageRuft Metadaten für einen einzelnen API-Schlüssel anhand seiner UUID ab.
POST/api/v1/api-keysapi:keys-manageErstellt einen neuen pi_live_- oder pi_test_-API-Schlüssel (request payload); gibt Klartext-key einmalig zurück.
PATCH / PUT/api/v1/api-keys/:idapi:keys-manageAktualisiert name, scopes oder expiresAt des Schlüssels (request payload).
DELETE/api/v1/api-keys/:idapi:keys-manageLöscht einen API-Schlüssel dauerhaft und schreibt einen API_KEY_DELETED-Audit-Log-Eintrag.
POST/api/v1/api-keys/:id/regenerateapi:keys-manageErzeugt ein neues geheimes Token unter Beibehaltung von id, name und scopes des Schlüssels.
POST/api/v1/api-keys/:id/activateapi:keys-manageReaktiviert einen zuvor deaktivierten API-Schlüssel sofort.
POST/api/v1/api-keys/:id/deactivateapi:keys-manageDeaktiviert einen API-Schlüssel per Soft-Delete (archivedAt-Zeitstempel), ohne die Konfiguration zu verlieren.
POST/api/v1/api-keys/:id/testapi:keys-managePrüft Schlüsselkonfiguration und Gültigkeitsstatus (API key verification result).
GET/api/v1/api-keys/:id/usageapi:keys-read oder api:keys-manageLiefert 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ßlich externalId-Abfragen und bundleId-.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)

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

Antwort (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
}

Wichtig: Das ungehashte Geheimnis data.key wird nur ein einziges Mal in der 201 Created- oder /regenerate-Antwort zurückgegeben. Nachfolgende GET /api/v1/api-keys-Aufrufe liefern ein maskiertes Präfix in key.

Den vollständigen Endpunkt-Katalog finden Sie in der API-Referenz und interaktive Spezifikationen unter /docs.

Weiterführende Produkt- & Entwicklerdoku

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.