Skip to content
Guide du centre d'aide · API développeur
5 min de lectureVérifié 2026-11-16

Présentation API & authentification

Maîtrisez les URLs (api.passinstance.com/api/v1), clés API vs jetons Scanner/SDK, en-têtes et limites de requêtes.

Dans ce guide

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

URLs de base & documentation interactive OpenAPI

Ressource / EnvironnementURLDescription
URL de base API Productionhttps://api.passinstance.com/api/v1Émission sur espace live, mises à jour push Wallet et scans en production.
URL de base Staging / Bac à sablehttps://staging-api.passinstance.com/api/v1Environnement isolé de tests de pré-production.
Swagger UI public interactifGET https://api.passinstance.com/api/public/docsSpécification OpenAPI 3.0 filtrée destinée aux développeurs tiers sur tous environnements.
Swagger UI complet hors-prodGET /api/docsInterface 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) :

FLUX ARCHITECTURE SYSTÈME
ARCHITECTURE INTERACTIVE
AUTHENTIFICATION API & CONTRÔLE DES PORTÉES
ACTEURS SYSTÈME PARTICIPANTS
P1 Client / Serveur backend
P2 Passerelle API & Gardes d'auth
P3 Contrôleur cible
ÉTAPE 1a REQUÊTE / ACTION Authorization: ApiKey
›
(API Key Authentication)
›
pi_live_...
›
Vérifier hash, expiration
›
& environnement (test/live)
›
Contrôler API_KEY_SCOPE_VALUES
›
(passes, templates, scans,
ÉTAPE 1b REQUÊTE / ACTION x-api-key: pi_live_...
›
webhooks, analytics, *)
ÉTAPE 1c REQUÊTE / ACTION x-scanner-key: <key>
›
(Scanner Key Authentication)
›
Limiter à /api/v1/scans
›
& /api/v1/scanner-keys
ÉTAPE 2 REQUÊTE / ACTION Isoler le locataire
ÉTAPE 3 RÉPONSE 200 OK API response (T)
›
<-------------------------------

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'identifiantEn-tête HTTPPréfixe / Format du jetonPérimètre autorisé
Clé API ProductionAuthorization: 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 à sableAuthorization: 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.0Authorization: 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 Scannerx-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éthodePoint d'entréePermission requise (api-key-permissions)Description
GET/api/v1/api-keysapi:keys-read ou api:keys-manageListe toutes les clés actives (et inactives avec ?includeInactive=true) avec valeurs key masquées.
GET/api/v1/api-keys/:idapi:keys-read ou api:keys-manageRécupère les métadonnées d'une clé API par UUID.
POST/api/v1/api-keysapi:keys-manageCré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/:idapi:keys-manageMet à jour name, scopes ou expiresAt d'une clé (request payload).
DELETE/api/v1/api-keys/:idapi:keys-manageSupprime définitivement une clé API et consigne une entrée d'audit API_KEY_DELETED.
POST/api/v1/api-keys/:id/regenerateapi:keys-manageGénère un nouveau jeton secret tout en conservant id, name et scopes.
POST/api/v1/api-keys/:id/activateapi:keys-manageRéactive immédiatement une clé API précédemment désactivée.
POST/api/v1/api-keys/:id/deactivateapi:keys-manageDésactive logiquement une clé API (archivedAt) sans perdre sa configuration.
POST/api/v1/api-keys/:id/testapi:keys-manageVérifie la configuration et l'état de validité de la clé (API key verification result).
GET/api/v1/api-keys/:id/usageapi:keys-read ou api:keys-manageRetourne 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 par externalId et téléchargements .pkpass par bundleId).
  • '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)

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

Réponse (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
}

Important : Le secret non haché data.key n'est retourné qu'une seule fois dans la réponse 201 Created ou /regenerate. Les appels ultérieurs sur GET /api/v1/api-keys renvoient un préfixe masqué dans key.

Parcourez le catalogue complet des points d'entrée dans Référence API et les spécifications interactives sur /docs.

Documentation produit et développeur associée

Prêt à lancer votre premier programme de cartes Wallet ?

Créez votre espace de travail, configurez votre modèle et testez une vraie carte dans Apple Wallet et Google Wallet avant de déployer à grande échelle.