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_...ofpi_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/:tokenof/d/:slug) door aan apparaten van eindgebruikers.
Basis-URL's en interactieve OpenAPI-documentatie
| Bron / Omgeving | URL | Beschrijving |
|---|---|---|
| Productie-API basis-URL | https://api.passinstance.com/api/v1 | Live pasuitgifte in werkruimten, push-updates voor wallets en productiescans. |
| Staging / Sandbox basis-URL | https://staging-api.passinstance.com/api/v1 | Geïsoleerde pre-productie testomgeving. |
| Openbare interactieve Swagger UI | GET https://api.passinstance.com/api/public/docs | Gefilterde OpenAPI 3.0-specificatie voor externe ontwikkelaars in alle omgevingen. |
| Volledige niet-prod Swagger UI | GET /api/docs | Volledige 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):
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 inloggegevens | HTTP-header | Tokenvoorvoegsel / Formaat | Toegestaan oppervlak |
|---|---|---|---|
| Productie API-sleutel | Authorization: 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-sleutel | Authorization: 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-token | Authorization: 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-apparaatsleutel | x-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:
| Methode | Eindpunt | Vereiste machtiging (api-key-permissions) | Beschrijving |
|---|---|---|---|
| GET | /api/v1/api-keys | api:keys-read of api:keys-manage | Toont alle actieve (en optioneel ?includeInactive=true) API-sleutels met gemaskeerde key-waarden. |
| GET | /api/v1/api-keys/:id | api:keys-read of api:keys-manage | Haalt metadata op voor één API-sleutel op basis van UUID. |
| POST | /api/v1/api-keys | api:keys-manage | Maakt een nieuwe pi_live_- of pi_test_-API-sleutel aan (request payload); retourneert eenmalig de onversleutelde key. |
PATCH / PUT | /api/v1/api-keys/:id | api:keys-manage | Werkt de name, scopes of expiresAt van de sleutel bij (request payload). |
| DELETE | /api/v1/api-keys/:id | api:keys-manage | Verwijdert een API-sleutel definitief en legt een API_KEY_DELETED-auditlogboekregistratie vast. |
| POST | /api/v1/api-keys/:id/regenerate | api:keys-manage | Genereert een nieuw geheim token met behoud van de id, name en scopes van de sleutel. |
| POST | /api/v1/api-keys/:id/activate | api:keys-manage | Schakelt een eerder gedeactiveerde API-sleutel onmiddellijk weer in. |
| POST | /api/v1/api-keys/:id/deactivate | api:keys-manage | Deactiveert een API-sleutel tijdelijk (archivedAt-tijdstempel) zonder verlies van configuratie. |
| POST | /api/v1/api-keys/:id/test | api:keys-manage | Verifieert de sleutelconfiguratie en geldigheidsstatus (API key verification result). |
| GET | /api/v1/api-keys/:id/usage | api:keys-read of api:keys-manage | Retourneert 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 opexternalIden.pkpass-downloads viabundleId). -
'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)
{
"name": "Shopify Checkout Issuance Worker",
"environment": "live",
"scopes": ["passes", "templates"],
"expiresAt": "2027-11-16T00:00:00.000Z"
}
Antwoord (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
}
Belangrijk: Het niet-gehashte geheim
data.keywordt slechts eenmaal geretourneerd in het201 Created- of/regenerate-antwoord. Volgende aanroepen naarGET /api/v1/api-keysretourneren een gemaskeerd voorvoegsel inkey.
Verken de volledige eindpuntcatalogus in de API-referentie en de interactieve specificaties op /docs.
