Authentification

L'API Partenaire supporte deux modes d'authentification :

Clé API partenaire (x-api-key) — recommandé pour les appels server-to-server.
JWT Bearer — utilisé pour les sessions authentifiées (back-office, comptes utilisateurs).

Les deux modes sont mutuellement compatibles : sur la plupart des endpoints partenaires, la clé API seule est suffisante.

Recommandation

Pour une integration machine-to-machine, utilise x-api-key comme mecanisme principal. Garde le JWT pour les cas ou un utilisateur authentifie agit depuis un back-office ou un contexte applicatif interne.

Le playground de la Reference API memorise localement la derniere valeur d authentification saisie. Une fois le JWT ou la cle technique colle, tu peux naviguer entre les endpoints et continuer les tests sans tout ressaisir.

1. Clé API partenaire (`x-api-key`)

Chaque partenaire dispose d'une clé API unique, générée par l'administrateur de la plateforme lors de l'onboarding. Cette clé est :

liée à un partnerId unique,
associée à un role partner (non-admin),
utilisable en production et en sandbox avec des valeurs distinctes.

Ne jamais exposer la clé API côté client (navigateur, mobile). Elle doit rester strictement côté serveur.

Exemple d'appel authentifié par clé API

curl -X POST "https://api.insurance-agg.example/api/v1/partner/contracts/auto/classic" \
  -H "x-api-key: ia_live_xxx" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 3b4f7a1e-8c90-4e2b-b6ab-1fdc0cabf111" \
  -d '{
    "returnUrl": "https://partner.example.com/payment/success",
    "cancelUrl": "https://partner.example.com/payment/failure",
    "contract": {
      "cliCode": "8400C000012",
      "cat": "550",
      "scatCode": "011",
      "carrCode": "10",
      "nrg": "E00001",
      "pfs": 1250,
      "nbP": 2,
      "dure": 1,
      "effet": "24/04/2026",
      "numImmat": "AA1250BM",
      "mqCode": "M00065",
      "modele": "R1250GS"
    }
  }'

2. JWT Bearer

Lorsque la requête provient d'un utilisateur authentifié (par exemple depuis votre back-office), un JWT peut être envoyé via le header Authorization.

curl -X GET "https://api.insurance-agg.example/api/v1/partner/contracts/requests/REF123" \
  -H "Authorization: Bearer eyJhbGciOi...redacted" \
  -H "x-api-key: pk_live_9f8a...redacted"

Les endpoints partenaires acceptent soit x-api-key, soit un JWT valide selon le contexte d'appel. En pratique, x-api-key est recommandé pour les intégrations server-to-server.

Headers recommandés

Header	Obligatoire	Description
`x-api-key`	Oui	Clé API partenaire.
`Authorization`	Non	`Bearer <jwt>` si appel dans un contexte utilisateur.
`idempotency-key`	Fortement recommandé	UUID v4 unique par tentative métier (voir section ci-dessous).
`x-request-id`	Recommandé	Identifiant traçant la requête côté partenaire (repris dans les logs).
`x-client-id`	Recommandé	Identifiant logique du sous-système appelant (ex: `mobile-app`, `back-office`).
`Content-Type`	Oui (POST/PATCH)	`application/json`.

Le couple minimum pour tester rapidement dans la doc est souvent: x-api-key + Content-Type: application/json pour les routes d ecriture.

`idempotency-key`

Pour toute opération non-idempotente (création de demande de contrat, configuration de webhook), envoyez un idempotency-key unique. En cas de retry réseau, rejouer la même clé permet d'éviter la duplication côté serveur.

La fenêtre d'idempotence dépend de la configuration serveur. Considérez la clé comme unique par opération métier.

Rôles et permissions

Rôle	Peut appeler
`partner`	Endpoints partenaire (`/partner/contracts/*`), configuration webhook personnel, lecture de ses propres contrats.
`admin`	Tout ce qui précède + endpoints `/contracts/auto/*` + configuration webhook d'un autre partenaire (`/partners/:partnerId/webhook`).

Un appel partner vers /contracts/auto/* renvoie 403 Forbidden.

Rotation des clés

Pour révoquer ou renouveler une clé API :

Contacter l'équipe intégration de l'agrégateur.
Déployer la nouvelle clé côté partenaire.
L'ancienne clé reste active pendant une fenêtre de grâce (par défaut 7 jours) pour absorber les rolling deployments.
Passé ce délai, l'ancienne clé est révoquée et retourne 401 Unauthorized.

Checklist auth avant prod

Cle production stockee dans un secret manager
Separation stricte sandbox / production
Aucune cle exposee cote navigateur
x-request-id propage dans les logs applicatifs
Procedure claire de rotation et revocation

Erreurs d'authentification courantes

Code	Cause
401	`x-api-key` manquant, invalide, ou révoqué.
401	JWT expiré ou signature invalide.
403	Clé valide mais rôle insuffisant (ex: `partner` appelant un route admin).

Voir Erreurs et troubleshooting pour la liste complète.

On this page