Clés API

Authentification des appels ministry : en-tête Authorization: Bearer sk_… sur la base https://paymentdev-api.akieni.tech/api/v1.

Format

Préfixe	Environnement	Usage
sk_test_…	Sandbox	Recette, connecteurs simulés selon configuration
sk_live_…	Production	Encaissements réels

La clé secrète complète n'est affichée qu'une fois à l'émission. Stockage dans un coffre de secrets ; jamais dans le navigateur, une application mobile ou un dépôt public.

Trois niveaux de portée

Chaque clé porte un scope qui fixe le tenant, l'application et les champs obligatoires à la création de session.

Scope	Portée	application_id implicite	tenant_id à POST /checkout/sessions
application	Une application métier (ex. portail casiers)	Oui, lié à la clé	Non requis
tenant	Toute la régie ; application intégrateur par défaut	Oui, application intégrateur de la régie	Non requis
platform	Plateforme DPI (eGouv, e-Citizen)	Oui, application intégrateur de la régie ciblée	Obligatoire (UUID ou slug)

Scope application

Clé émise pour une application ministry nominative. Toutes les sessions créées sont rattachées à cette application et au tenant de la régie propriétaire.

Cas d'usage : intégration directe d'un SI ministériel (MinJust, autre ministère) avec une application dédiée et des endpoints webhook propres.

Scope tenant

Clé au niveau régie. L'API rattache les sessions à l'application intégrateur par défaut du tenant. Une seule clé peut servir plusieurs flux métier si l'architecture le justifie.

Cas d'usage : intégrateur unique par ministère, plusieurs services métier derrière la même clé.

Scope platform

Clé transversale opérée par un intégrateur plateforme (eGouv). Chaque POST /checkout/sessions et chaque POST /checkout/sessions/verify-completion doit inclure tenant_id identifiant la régie cible.

Sans tenant_id : réponse 400 checkout.tenant_required.

Les webhooks (checkout.completed, etc.) sont livrés en fan-out dual : endpoints de l'application intégrateur de la régie ciblée, et endpoints eGouv configurés dans admin → Intégration eGouv (indépendants des clés API).

Résolution du contexte

À chaque requête, l'API :

1. Valide le préfixe et le hash de la clé (sk_ secret uniquement).
2. Vérifie que le tenant et l'application sont actifs et compatibles avec l'environnement de la clé (test / live).
3. Résout service_code optionnel contre le catalogue de services actifs de la régie.

Clé invalide, inactive ou non autorisée pour la ressource : 401. Tenant ou application inaccessible pour la clé : 403.

Champs liés au scope

Endpoint	Champ	Scope application / tenant	Scope platform
POST /checkout/sessions	tenant_id	Ignoré (tenant de la clé)	Obligatoire
POST /checkout/sessions/verify-completion	tenant_id	Optionnel (filtrage)	Recommandé (UUID régie cible)
GET /checkout/sessions	tenant_id (query)	Optionnel	Optionnel (contexte plateforme)

Environnements

Ne pas mélanger clés, secrets webhook et URLs checkout entre sandbox et production. Une clé sk_test_* ne crée pas de sessions visibles avec une clé sk_live_*.

Émission et rotation

Émission : portail régie (officer) ou super-admin. Pas d'API self-service ministry pour créer ou révoquer des clés en v1.

Révoquer une clé compromise : désactivation côté plateforme, émission d'une nouvelle clé, mise à jour du coffre de secrets côté SI.