Skip to content
Guida del Centro assistenza · API per sviluppatori
4 min di letturaVerificato 2026-11-16

Panoramica API e autenticazione

URL di base (api.passinstance.com/api/v1), chiavi API vs token Scanner/SDK, header e limiti di frequenza.

In questa guida

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_... o pi_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/:token oppure /d/:slug).

URL di base e documentazione OpenAPI interattiva

Risorsa / AmbienteURLDescrizione
URL di base API di Produzionehttps://api.passinstance.com/api/v1Emissione nel workspace live, aggiornamenti push Wallet e scansioni di produzione.
URL di base Staging / Sandboxhttps://staging-api.passinstance.com/api/v1Ambiente di test isolato di pre-produzione.
Swagger UI pubblica interattivaGET https://api.passinstance.com/api/public/docsSpecifica OpenAPI 3.0 filtrata per sviluppatori terzi in tutti gli ambienti.
Swagger UI completa Non-ProdGET /api/docsSwagger 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):

FLUSSO ARCHITETTURALE
ARCHITETTURA INTERATTIVA
AUTENTICAZIONE API E VERIFICA DEGLI AMBITI
ATTORI DI SISTEMA COINVOLTI
P1 Client / Server Backend
P2 API Gateway e Guard di auth
P3 Controller di destinazione
FASE 1a RICHIESTA / AZIONE Authorization: ApiKey
›
(API Key Authentication)
›
pi_live_...
›
Verifica hash chiave,
›
scadenza e ambiente
›
Controlla API_KEY_SCOPE_VALUES
›
(passes, templates, scans,
FASE 1b RICHIESTA / AZIONE x-api-key: pi_live_...
›
webhooks, analytics, *)
FASE 1c RICHIESTA / AZIONE x-scanner-key: <key>
›
(Scanner Key Authentication)
›
Limita a /api/v1/scans
›
e /api/v1/scanner-keys
FASE 2 RICHIESTA / AZIONE Impone isolamento tenant
FASE 3 RISPOSTA 200 OK API response (T)
›
<-------------------------------

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 credenzialeHeader HTTPPrefisso / Formato tokenSuperficie consentita
Chiave API di ProduzioneAuthorization: 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 SandboxAuthorization: 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.0Authorization: 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 Scannerx-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:

MetodoEndpointPermesso richiesto (api-key-permissions)Descrizione
GET/api/v1/api-keysapi:keys-read o api:keys-manageElenca tutte le chiavi API attive (e opzionalmente ?includeInactive=true) con valori key mascherati.
GET/api/v1/api-keys/:idapi:keys-read o api:keys-manageRecupera i metadati di una singola chiave API tramite UUID.
POST/api/v1/api-keysapi:keys-manageCrea una nuova chiave API pi_live_ o pi_test_ (request payload); restituisce key in chiaro una sola volta.
PATCH / PUT/api/v1/api-keys/:idapi:keys-manageAggiorna name, scopes o expiresAt della chiave (request payload).
DELETE/api/v1/api-keys/:idapi:keys-manageElimina definitivamente una chiave API e registra una voce di audit API_KEY_DELETED.
POST/api/v1/api-keys/:id/regenerateapi:keys-manageGenera un nuovo token segreto preservando id, name e scopes della chiave.
POST/api/v1/api-keys/:id/activateapi:keys-manageRiattiva immediatamente una chiave API precedentemente disattivata.
POST/api/v1/api-keys/:id/deactivateapi:keys-manageDisattiva logicamente una chiave API (timestamp archivedAt) senza perdere la configurazione.
POST/api/v1/api-keys/:id/testapi:keys-manageVerifica configurazione e stato di validità della chiave (API key verification result).
GET/api/v1/api-keys/:id/usageapi:keys-read o api:keys-manageRestituisce 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 per externalId e download .pkpass per bundleId).
  • '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)

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

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

Importante: Il segreto non sottoposto ad hashing data.key viene restituito una sola volta nella risposta 201 Created o /regenerate. Le chiamate successive a GET /api/v1/api-keys restituiscono un prefisso mascherato in key.

Esplori il catalogo completo degli endpoint in Riferimento API e le specifiche interattive su /docs.

Documentazione prodotto e API correlata

Pronto a lanciare il tuo primo programma di carte Wallet?

Crea il tuo workspace, configura il modello e testa una carta reale in Apple Wallet e Google Wallet prima di scalare.