Panoramica
La REST API di Passinstance consente l'emissione server-to-server dei pass, la gestione dei modelli, la modifica dei saldi in tempo reale, l'orchestrazione dei webhook e l'estrazione di dati analitici. Tutti gli endpoint standard sono esposti sotto il percorso di base versionato https://api.passinstance.com/api/v1, accettano e restituiscono JSON UTF-8 (Content-Type: application/json) e racchiudono le risposte standard in un envelope deterministico API response (T).
Importante: Non incorpori mai le chiavi API del workspace (
pi_live_...opi_test_...) all'interno di JavaScript lato client nel browser, pacchetti binari di app mobili o repository Git pubblici. Richiami sempre l'API di Passinstance dal proprio server backend e trasmetta ai dispositivi degli utenti finali soltanto lo smart link di download risultante (/s/:tokenoppure/d/:slug).
URL di base e documentazione OpenAPI interattiva
| Risorsa / Ambiente | URL | Descrizione |
|---|---|---|
| URL di base API di Produzione | https://api.passinstance.com/api/v1 | Emissione nel workspace live, aggiornamenti push Wallet e scansioni di produzione. |
| URL di base Staging / Sandbox | https://staging-api.passinstance.com/api/v1 | Ambiente di test isolato di pre-produzione. |
| Swagger UI pubblica interattiva | GET https://api.passinstance.com/api/public/docs | Specifica OpenAPI 3.0 filtrata per sviluppatori terzi in tutti gli ambienti. |
| Swagger UI completa Non-Prod | GET /api/docs | Swagger UI interna completa generata negli ambienti non di produzione (incorporata anche in /settings/workspace/developer nella Dashboard). |
Architettura di autenticazione e regole d'ambiente
Passinstance impone una rigorosa separazione dell'ambito di impatto tra tre famiglie di credenziali (API Key Authentication, OAuth 2.0 Authentication e Scanner Key Authentication):
Header di autenticazione supportati e API_KEY_ENVIRONMENT_VALUES
request payload.environment utilizza API_KEY_ENVIRONMENT_VALUES ('test' | 'live'). Le chiavi sandbox (pi_test_...) sono valide soltanto sui workspace sandbox, mentre le chiavi live (pi_live_...) sono valide soltanto sui workspace di produzione:
| Tipo di credenziale | Header HTTP | Prefisso / Formato token | Superficie consentita |
|---|---|---|---|
| Chiave API di Produzione | Authorization: ApiKey pi_live_... oppure x-api-key: pi_live_... | pi_live_<secret> (environment: "live") | Chiamate API sul workspace di produzione corrispondenti agli API_KEY_SCOPE_VALUES assegnati. |
| Chiave API Sandbox | Authorization: ApiKey pi_test_... oppure x-api-key: pi_test_... | pi_test_<secret> (environment: "test") | Test sul workspace sandbox e suite di integrazione CI/CD automatizzate. |
| Token Bearer OAuth 2.0 | Authorization: Bearer <jwt> | JWT firmato (OAuth 2.0 Authentication + Permission Scope Validation) | Piattaforme iPaaS connesse (Zapier, Make) mediante ambiti OAuth granulari (webhooks:read, webhooks:write, templates:read). |
| Chiave dispositivo Scanner | x-scanner-key: <scanner-key> | <scanner-key> (Scanner Key Authentication) | Rigorosamente isolata a /api/v1/scans, /api/v1/scanner-keys e alle route di scansione meccaniche. |
Gestione delle chiavi API (API Keys API e UI Dashboard)
Gestisca le credenziali visivamente in Impostazioni Workspace -> Sviluppatore -> Credenziali API (/settings/workspace/developer/api-credentials, oppure /platform/api-keys) o programmaticamente tramite /api/v1/api-keys:
| Metodo | Endpoint | Permesso richiesto (api-key-permissions) | Descrizione |
|---|---|---|---|
| GET | /api/v1/api-keys | api:keys-read o api:keys-manage | Elenca tutte le chiavi API attive (e opzionalmente ?includeInactive=true) con valori key mascherati. |
| GET | /api/v1/api-keys/:id | api:keys-read o api:keys-manage | Recupera i metadati di una singola chiave API tramite UUID. |
| POST | /api/v1/api-keys | api:keys-manage | Crea una nuova chiave API pi_live_ o pi_test_ (request payload); restituisce key in chiaro una sola volta. |
PATCH / PUT | /api/v1/api-keys/:id | api:keys-manage | Aggiorna name, scopes o expiresAt della chiave (request payload). |
| DELETE | /api/v1/api-keys/:id | api:keys-manage | Elimina definitivamente una chiave API e registra una voce di audit API_KEY_DELETED. |
| POST | /api/v1/api-keys/:id/regenerate | api:keys-manage | Genera un nuovo token segreto preservando id, name e scopes della chiave. |
| POST | /api/v1/api-keys/:id/activate | api:keys-manage | Riattiva immediatamente una chiave API precedentemente disattivata. |
| POST | /api/v1/api-keys/:id/deactivate | api:keys-manage | Disattiva logicamente una chiave API (timestamp archivedAt) senza perdere la configurazione. |
| POST | /api/v1/api-keys/:id/test | api:keys-manage | Verifica configurazione e stato di validità della chiave (API key verification result). |
| GET | /api/v1/api-keys/:id/usage | api:keys-read o api:keys-manage | Restituisce telemetria delle richieste, latenze medie e ripartizione dei codici di stato HTTP (API key usage summary). |
Ambiti disponibili per le chiavi API (API_KEY_SCOPE_VALUES)
Esegua sempre il principio del privilegio minimo assegnando solo gli ambiti necessari a ciascun worker backend (se omesso, il valore predefinito è ["*"]):
-
'passes'— Emettere, ispezionare, aggiornare, annullare e ricercare istanze pass (incluse ricerche perexternalIde download.pkpassperbundleId). -
'templates'— Leggere schemi dei modelli, attributi personalizzati e meccaniche. -
'scans'— Eseguire validazioni, ispezionare esiti di scansione e avviare meccaniche. -
'webhooks'— Gestire sottoscrizioni webhook e interrogare le code pull-webhook. -
'analytics'— Interrogare metriche di emissione pass, registrazioni dispositivi e quote Wallet. -
'*'— Accesso amministrativo completo su tutti i domini dell'API sviluppatore.
Creazione di una chiave API con ambito limitato (POST /api/v1/api-keys)
{
"name": "Shopify Checkout Issuance Worker",
"environment": "live",
"scopes": ["passes", "templates"],
"expiresAt": "2027-11-16T00:00:00.000Z"
}
Risposta (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
}
Importante: Il segreto non sottoposto ad hashing
data.keyviene restituito una sola volta nella risposta201 Createdo/regenerate. Le chiamate successive aGET /api/v1/api-keysrestituiscono un prefisso mascherato inkey.
Esplori il catalogo completo degli endpoint in Riferimento API e le specifiche interattive su /docs.
