Aperçu
L'API REST Passinstance permet d'émettre des passes de serveur à serveur, de piloter vos modèles, de modifier les soldes en temps réel, d'orchestrer des webhooks et d'extraire vos statistiques. Tous les points d'entrée standard sont montés sous le chemin de base versionné https://api.passinstance.com/api/v1, acceptent et retournent du JSON encodé en UTF-8 (Content-Type: application/json), et encapsulent les réponses standard dans une enveloppe déterministe API response (T).
Important : N'embarquez jamais de clés API d'espace de travail (
pi_live_...oupi_test_...) dans du JavaScript navigateur côté client, des binaires d'applications mobiles ou des dépôts Git publics. Appelez systématiquement l'API Passinstance depuis votre serveur backend et ne transmettez aux terminaux finaux que l'URL de téléchargement intelligente résultante (/s/:tokenou/d/:slug).
URLs de base & documentation interactive OpenAPI
| Ressource / Environnement | URL | Description |
|---|---|---|
| URL de base API Production | https://api.passinstance.com/api/v1 | Émission sur espace live, mises à jour push Wallet et scans en production. |
| URL de base Staging / Bac à sable | https://staging-api.passinstance.com/api/v1 | Environnement isolé de tests de pré-production. |
| Swagger UI public interactif | GET https://api.passinstance.com/api/public/docs | Spécification OpenAPI 3.0 filtrée destinée aux développeurs tiers sur tous environnements. |
| Swagger UI complet hors-prod | GET /api/docs | Interface Swagger UI interne complète générée en environnement hors production (également intégrée sous /settings/workspace/developer dans le tableau de bord). |
Architecture d'authentification & règles d'environnement
Passinstance applique une séparation stricte du rayon d'impact entre trois familles d'identifiants (API Key Authentication, OAuth 2.0 Authentication et Scanner Key Authentication) :
En-têtes d'authentification pris en charge & API_KEY_ENVIRONMENT_VALUES
request payload.environment utilise API_KEY_ENVIRONMENT_VALUES ('test' \| 'live'). Les clés bac à sable (pi_test_...) ne fonctionnent que sur des espaces bac à sable, tandis que les clés live (pi_live_...) ne fonctionnent que sur des espaces de production :
| Type d'identifiant | En-tête HTTP | Préfixe / Format du jeton | Périmètre autorisé |
|---|---|---|---|
| Clé API Production | Authorization: ApiKey pi_live_... ou x-api-key: pi_live_... | pi_live_<secret> (environment: "live") | Appels API sur espace de production selon les API_KEY_SCOPE_VALUES assignés. |
| Clé API Bac à sable | Authorization: ApiKey pi_test_... ou x-api-key: pi_test_... | pi_test_<secret> (environment: "test") | Tests en espace bac à sable et suites d'intégration CI/CD automatisées. |
| Jeton Bearer OAuth 2.0 | Authorization: Bearer <jwt> | JWT signé (OAuth 2.0 Authentication + Permission Scope Validation) | Plateformes iPaaS connectées (Zapier, Make) avec portées OAuth granulaires (webhooks:read, webhooks:write, templates:read). |
| Clé d'appareil Scanner | x-scanner-key: <scanner-key> | <scanner-key> (Scanner Key Authentication) | Strictement isolée aux routes /api/v1/scans, /api/v1/scanner-keys et aux points d'entrée de scan de mécaniques. |
Gestion des clés API (API Keys API & interface tableau de bord)
Gérez vos identifiants visuellement dans Paramètres de l'espace -> Développeur -> Identifiants API (/settings/workspace/developer/api-credentials, ou /platform/api-keys) ou par API via /api/v1/api-keys :
| Méthode | Point d'entrée | Permission requise (api-key-permissions) | Description |
|---|---|---|---|
| GET | /api/v1/api-keys | api:keys-read ou api:keys-manage | Liste toutes les clés actives (et inactives avec ?includeInactive=true) avec valeurs key masquées. |
| GET | /api/v1/api-keys/:id | api:keys-read ou api:keys-manage | Récupère les métadonnées d'une clé API par UUID. |
| POST | /api/v1/api-keys | api:keys-manage | Crée une nouvelle clé API pi_live_ ou pi_test_ (request payload) ; retourne le secret key en clair une seule fois. |
PATCH / PUT | /api/v1/api-keys/:id | api:keys-manage | Met à jour name, scopes ou expiresAt d'une clé (request payload). |
| DELETE | /api/v1/api-keys/:id | api:keys-manage | Supprime définitivement une clé API et consigne une entrée d'audit API_KEY_DELETED. |
| POST | /api/v1/api-keys/:id/regenerate | api:keys-manage | Génère un nouveau jeton secret tout en conservant id, name et scopes. |
| POST | /api/v1/api-keys/:id/activate | api:keys-manage | Réactive immédiatement une clé API précédemment désactivée. |
| POST | /api/v1/api-keys/:id/deactivate | api:keys-manage | Désactive logiquement une clé API (archivedAt) sans perdre sa configuration. |
| POST | /api/v1/api-keys/:id/test | api:keys-manage | Vérifie la configuration et l'état de validité de la clé (API key verification result). |
| GET | /api/v1/api-keys/:id/usage | api:keys-read ou api:keys-manage | Retourne la télémétrie d'appels, latences moyennes et répartition des codes HTTP (API key usage summary). |
Portées disponibles des clés API (API_KEY_SCOPE_VALUES)
Appliquez le principe du moindre privilège en n'accordant que les portées indispensables à chaque service backend (par défaut ["*"] si omis) :
-
'passes'— Émettre, consulter, mettre à jour, invalider et rechercher des instances de passes (y compris parexternalIdet téléchargements.pkpassparbundleId). -
'templates'— Lire les schémas de modèles, attributs personnalisés et mécaniques. -
'scans'— Exécuter des validations, consulter les résultats de scan et déclencher des mécaniques. -
'webhooks'— Gérer les abonnements webhook et interroger les files de pull-webhooks. -
'analytics'— Interroger les métriques d'émission, d'enregistrements d'appareils et de répartition des portefeuilles. -
'*'— Accès administratif complet à tous les domaines de l'API développeur.
Créer une clé API à portée restreinte (POST /api/v1/api-keys)
{
"name": "Shopify Checkout Issuance Worker",
"environment": "live",
"scopes": ["passes", "templates"],
"expiresAt": "2027-11-16T00:00:00.000Z"
}
Réponse (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
}
Important : Le secret non haché
data.keyn'est retourné qu'une seule fois dans la réponse201 Createdou/regenerate. Les appels ultérieurs surGET /api/v1/api-keysrenvoient un préfixe masqué danskey.
Parcourez le catalogue complet des points d'entrée dans Référence API et les spécifications interactives sur /docs.
