Comment s'authentifier auprès de l'API ?

Toute route sous /v1/ attend l'en-tête « Authorization: Bearer <clé> ». Deux sortes de porteurs : une clé d'API (préfixe qiv_), pour un logiciel qui agit seul pour une société ; ou le jeton d'identité d'une personne connectée, pour une interface.

Clé d'API : le cas ordinaire d'une intégration

Authorization: Bearer qiv_…

• Rattachée à une société, par son stockage : elle ne peut pas en changer.
• Porte un ensemble de permissions choisi à sa création, jamais un rôle.
• Peut porter une date d'expiration (expires_at, format RFC 3339) si elle est créée par l'API.

Jeton d'identité : une personne connectée

Le jeton d'identité (id_token) rendu par les routes de connexion /v1/auth/*. Il désigne une personne, pas une société ; ses sociétés et ses droits sont lus par le serveur à chaque requête. Il sert aux interfaces où un utilisateur se connecte lui-même ; pour un serveur qui travaille seul, prenez une clé.

Les réponses d'échec

Situation	Réponse
En-tête absent	401, « Authentification manquante. Attendu : en-tête Authorization: Bearer <clé d'API ou jeton>. »
Clé inconnue, révoquée ou expirée ; jeton forgé ou périmé	401, « Authentification invalide ou expirée. »
Service d'identité momentanément injoignable	503 identity_provider_unavailable : réessayez, ne reconnectez pas l'utilisateur

Pourquoi un seul message pour « inconnue », « révoquée » et « expirée »

Les distinguer aiderait quelqu'un qui essaie des clés au hasard. La clé, elle, n'est jamais stockée en clair : seule son empreinte l'est, et une révocation vaut dès la requête suivante.

Mis à jour le 30 septembre 2026.