Skip to content
Helpcentrum-gids · Ontwikkelaars-API
4 min leestijdGecontroleerd 2026-11-16

API-overzicht & authenticatie

Basis-URL's (api.passinstance.com/api/v1), API-sleutels vs. Scanner-/SDK-tokens, headers en snelheidslimieten.

In deze gids

Overzicht

De Passinstance REST API maakt server-naar-server pasuitgifte, sjabloonbeheer, realtime saldomutaties, webhook-orkestratie en analytics-extractie mogelijk. Alle standaard eindpunten zijn gekoppeld onder het van versie voorziene basispad https://api.passinstance.com/api/v1, accepteren en retourneren UTF-8 JSON (Content-Type: application/json), en verpakken standaardantwoorden in een deterministische API response (T)-envelop.

Belangrijk: Sluit API-sleutels van uw werkruimte (pi_live_... of pi_test_...) nooit in binnen client-side browser-JavaScript, binaire bestanden van mobiele applicaties of openbare Git-repository's. Roep de Passinstance API altijd aan vanaf uw backendserver en geef uitsluitend de resulterende slimme download-URL (/s/:token of /d/:slug) door aan apparaten van eindgebruikers.

Basis-URL's en interactieve OpenAPI-documentatie

Bron / OmgevingURLBeschrijving
Productie-API basis-URLhttps://api.passinstance.com/api/v1Live pasuitgifte in werkruimten, push-updates voor wallets en productiescans.
Staging / Sandbox basis-URLhttps://staging-api.passinstance.com/api/v1Geïsoleerde pre-productie testomgeving.
Openbare interactieve Swagger UIGET https://api.passinstance.com/api/public/docsGefilterde OpenAPI 3.0-specificatie voor externe ontwikkelaars in alle omgevingen.
Volledige niet-prod Swagger UIGET /api/docsVolledige interne Swagger UI gegenereerd in niet-productieomgevingen (ook ingesloten op /settings/workspace/developer in het Dashboard).

Authenticatie-architectuur en omgevingsregels

Passinstance handhaaft een strikte scheiding van de impactradius over drie typen inloggegevens (API Key Authentication, OAuth 2.0 Authentication en Scanner Key Authentication):

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SYSTEEMARCHITECTUURSTROOM: API-AUTHENTICATIE & SCOPEVERIFICATIE
DEELNEMENDE SYSTEEMACTOREN
P1 Client / Backendserver
P2 API Gateway & Auth Guards
P3 Doelcontroller
STAP 1a VERZOEK / ACTIE Authorization: ApiKey
›
(API Key Authentication)
›
pi_live_...
›
Verifieer sleutelhash, verval
›
& omgeving (test vs live)
›
Controleer API_KEY_SCOPE_
›
VALUES (passes, templates,
STAP 1b VERZOEK / ACTIE x-api-key: pi_live_...
›
scans, webhooks, analytics,*)
STAP 1c VERZOEK / ACTIE x-scanner-key: <key>
›
(Scanner Key Authentication)
›
Beperk tot /api/v1/scans
›
& /api/v1/scanner-keys
STAP 2 VERZOEK / ACTIE Dwing tenant-isolatie af
STAP 3 ANTWOORD 200 OK API response (T) --
›
<-------------------------------

Ondersteunde authenticatieheaders & API_KEY_ENVIRONMENT_VALUES

request payload.environment gebruikt API_KEY_ENVIRONMENT_VALUES ('test' | 'live'). Sandboxsleutels (pi_test_...) zijn uitsluitend geldig in sandboxwerkruimten, terwijl livesleutels (pi_live_...) uitsluitend geldig zijn in productiewerkruimten:

Type inloggegevensHTTP-headerTokenvoorvoegsel / FormaatToegestaan oppervlak
Productie API-sleutelAuthorization: ApiKey pi_live_... of x-api-key: pi_live_...pi_live_<secret> (environment: "live")API-aanroepen voor productiewerkruimten die overeenkomen met de toegewezen API_KEY_SCOPE_VALUES.
Sandbox API-sleutelAuthorization: ApiKey pi_test_... of x-api-key: pi_test_...pi_test_<secret> (environment: "test")Testen in sandboxwerkruimten en geautomatiseerde CI/CD-integratiesuites.
OAuth 2.0 Bearer-tokenAuthorization: Bearer <jwt>Ondertekende JWT (OAuth 2.0 Authentication + Permission Scope Validation)Verbonden iPaaS-platforms (Zapier, Make) met fijnmazige OAuth-scopes (webhooks:read, webhooks:write, templates:read).
Scanner-apparaatsleutelx-scanner-key: <scanner-key><scanner-key> (Scanner Key Authentication)Strikt geïsoleerd tot /api/v1/scans, /api/v1/scanner-keys en scanroutes voor mechanieken.

Beheer van API-sleutels (API Keys API & Dashboard-UI)

Beheer inloggegevens visueel via Werkruimte-instellingen -> Ontwikkelaar -> API-inloggegevens (/settings/workspace/developer/api-credentials, of /platform/api-keys) of programmatisch via /api/v1/api-keys:

MethodeEindpuntVereiste machtiging (api-key-permissions)Beschrijving
GET/api/v1/api-keysapi:keys-read of api:keys-manageToont alle actieve (en optioneel ?includeInactive=true) API-sleutels met gemaskeerde key-waarden.
GET/api/v1/api-keys/:idapi:keys-read of api:keys-manageHaalt metadata op voor één API-sleutel op basis van UUID.
POST/api/v1/api-keysapi:keys-manageMaakt een nieuwe pi_live_- of pi_test_-API-sleutel aan (request payload); retourneert eenmalig de onversleutelde key.
PATCH / PUT/api/v1/api-keys/:idapi:keys-manageWerkt de name, scopes of expiresAt van de sleutel bij (request payload).
DELETE/api/v1/api-keys/:idapi:keys-manageVerwijdert een API-sleutel definitief en legt een API_KEY_DELETED-auditlogboekregistratie vast.
POST/api/v1/api-keys/:id/regenerateapi:keys-manageGenereert een nieuw geheim token met behoud van de id, name en scopes van de sleutel.
POST/api/v1/api-keys/:id/activateapi:keys-manageSchakelt een eerder gedeactiveerde API-sleutel onmiddellijk weer in.
POST/api/v1/api-keys/:id/deactivateapi:keys-manageDeactiveert een API-sleutel tijdelijk (archivedAt-tijdstempel) zonder verlies van configuratie.
POST/api/v1/api-keys/:id/testapi:keys-manageVerifieert de sleutelconfiguratie en geldigheidsstatus (API key verification result).
GET/api/v1/api-keys/:id/usageapi:keys-read of api:keys-manageRetourneert verzoektelemetrie, gemiddelde latentie en uitsplitsing naar HTTP-statuscodes (API key usage summary).

Beschikbare scopes voor API-sleutels (API_KEY_SCOPE_VALUES)

Volg het principe van minimale rechten door alleen de scopes toe te wijzen die elke backend-worker nodig heeft (standaard ingesteld op ["*"] indien weggelaten):

  • 'passes' — Pasinstanties uitgeven, inspecteren, bijwerken, ongeldig verklaren en doorzoeken (inclusief zoekopdrachten op externalId en .pkpass-downloads via bundleId).
  • 'templates' — Sjabloonschema's, aangepaste attributen en mechanieken uitlezen.
  • 'scans' — Validaties uitvoeren, scanresultaten inspecteren en mechanieken activeren.
  • 'webhooks' — Webhookabonnementen beheren en pull-webhookwachtrijen uitlezen.
  • 'analytics' — Statistieken over pasuitgifte, apparaatregistraties en wallet-aandeel opvragen.
  • '*' — Volledige administratieve toegang over alle ontwikkelaars-API-domeinen.

Een gescopete API-sleutel aanmaken (POST /api/v1/api-keys)

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

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

Belangrijk: Het niet-gehashte geheim data.key wordt slechts eenmaal geretourneerd in het 201 Created- of /regenerate-antwoord. Volgende aanroepen naar GET /api/v1/api-keys retourneren een gemaskeerd voorvoegsel in key.

Verken de volledige eindpuntcatalogus in de API-referentie en de interactieve specificaties op /docs.

Gerelateerde product- en ontwikkelaarsdocs

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.