# Clés API Un cookie de session convient à un navigateur et à rien d'autre. Lorsqu'un script, un job de CI ou un service doit appeler votre instance, il lui faut un identifiant qu'il puisse détenir — et les **clés API en libre-service** sont cet identifiant : un utilisateur connecté crée sa propre clé, la présente dans l'en-tête `x-api-key`, et la révoque une fois le travail terminé. Les clés sont désactivées par défaut. Un seul booléen les active. ```yaml auth: strategies: - type: emailAndPassword apiKeys: true ``` | Propriété | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `apiKeys` | Booléen. `true` monte les endpoints `/api/auth/api-key/*` et fait de `x-api-key` un identifiant valide sur toute route protégée. Omis (valeur par défaut), la fonctionnalité est inactive. | Lorsque l'option est absente, la surface ne reconnaît pas sa propre existence : `/api/auth/api-key/*` répond **404**, et un en-tête `x-api-key` est purement ignoré. ## S'authentifier avec une clé Présentez la clé dans l'en-tête **`x-api-key`**. Elle fonctionne sur toute route `/api/*` protégée, depuis n'importe quel client — sans cookie, sans aller-retour de connexion. ```bash curl -H "x-api-key: $SOVRIUM_API_KEY" \ http://localhost:3000/api/tables/notes/records ``` :::callout **`Authorization: Bearer` n'authentifie rien.** Sovrium accepte exactement deux formes d'identifiant sur `/api/*` : le cookie de session et `x-api-key`. Une clé valide présentée comme jeton Bearer ne résout aucune session et renvoie `401` — un contrat délibéré, afin qu'un identifiant durable emprunte un seul chemin audité plutôt que deux. Si une requête qui devrait aboutir renvoie `401`, vérifiez d'abord le nom de l'en-tête. ::: ## Créer, lister et révoquer Quatre endpoints, montés sous `/api/auth/api-key/`. Chacun est limité à la session appelante : un utilisateur voit et gère **ses propres** clés, et celles de personne d'autre. | Méthode | Chemin | Corps / requête | Rôle | | ------- | -------------------------- | ------------------------- | ---------------------------------------------------------------------- | | `POST` | `/api/auth/api-key/create` | `{ "name": "CI deploy" }` | Créer une clé. La réponse porte la valeur en clair **une seule fois**. | | `GET` | `/api/auth/api-key/list` | — | Lister les clés de l'appelant (métadonnées uniquement). | | `GET` | `/api/auth/api-key/get` | `?id=` | Relire une des clés de l'appelant par son id. | | `POST` | `/api/auth/api-key/delete` | `{ "keyId": "" }` | Révoquer une clé. | Créer une clé depuis une session de navigateur authentifiée : ```bash curl -X POST http://localhost:3000/api/auth/api-key/create \ -H "Content-Type: application/json" \ -b cookies.txt \ -d '{ "name": "Nightly backup job" }' ``` ```json { "id": "aK9tZ...", "name": "Nightly backup job", "key": "sk_live_9f2c...", "createdAt": "2026-08-26T09:14:22.000Z" } ``` `key` est la seule chose que vous ayez à conserver. Stockez-la là où le job lit ses secrets. :::callout **Affichée une fois, puis plus jamais.** Seule la réponse de création porte la valeur en clair. `list` et `get` décrivent une clé — id, nom, horodatages — mais ne la réémettent jamais, sous aucun nom de champ, parce que le serveur ne la détient pas : la colonne stockée contient une empreinte SHA-256, pas l'identifiant. Quelqu'un capable de lire votre base de données ne peut toujours pas s'authentifier avec ce qu'il y trouve. Si la valeur est perdue, le remède est de révoquer et d'en créer une nouvelle. ::: La révocation est une **suppression**, pas un indicateur : la ligne disparaît, et la requête identique qui aboutissait un instant plus tôt répond `401`. Donnez à chaque clé le nom du job qui la portera. Les noms sont ce qui vous permettra, six mois plus tard, de distinguer la clé du pipeline de CI de celle du script de reporting que vous avez mis hors service. ## Ce qu'une clé a le droit de faire Une clé porte le rôle de l'utilisateur qui l'a créée — **résolu en direct, à chaque requête**, et non figé à la création. - La clé d'un `member` peut faire exactement ce que ce membre peut faire. Jamais davantage. - Promouvez ou rétrogradez le propriétaire et ses clés existantes suivent immédiatement. Rétrograder un utilisateur restreint toutes les clés qu'il détient, sans en invalider aucune. - Un appelant ne peut pas élargir sa propre clé. Fournir des permissions au moment de la création ne produit pas de clé privilégiée — l'habilitation dépend de qui demande, jamais de ce qui est demandé. C'est pourquoi une clé n'a besoin d'aucune configuration de permissions propre : elle est une seconde façon de présenter une identité que vous détenez déjà, pas une nouvelle identité. ### Un bannissement suspend une clé ; le lever la rétablit Bannir un utilisateur empêche ses clés de s'authentifier, immédiatement et sur toutes les routes. La ligne de la clé reste intacte, si bien que lever le bannissement rétablit les mêmes clés — un bannissement suspend un identifiant plutôt que de le détruire, ce qui importe puisque Better Auth lève seul un bannissement temporaire à son échéance. Sovrium ne définit aucune expiration : une clé reste valide jusqu'à sa révocation ou jusqu'au bannissement de son propriétaire. Traitez-la comme un mot de passe : limitez-la à un usage, conservez-la dans un gestionnaire de secrets, et révoquez-la quand le travail est terminé. ## La page de console Les opérateurs connectés gèrent leurs propres clés sur **`/_admin/api-keys`** — créer, copier une fois, révoquer — aux côtés des autres pages relatives à leur compte dans le [tableau de bord d'administration](/fr/docs/admin-dashboard). La console reste derrière la barrière habituelle `/_admin/*` réservée aux administrateurs, mais pas l'API : **tout utilisateur connecté peut créer et utiliser des clés** via `/api/auth/api-key/*`. Un `member` qui ne voit jamais le tableau de bord peut malgré tout détenir une clé et authentifier un script avec elle. ## À ne pas confondre avec une Connexion Deux fonctionnalités de Sovrium mettent en jeu ce qu'on appelle une clé API, et elles pointent dans des directions opposées. | | **Clés API** (cette page) | **[Connexions](/fr/docs/automation-connections)** | | ------------------- | -------------------------------------------- | ------------------------------------------------- | | Direction | **Entrante** — identifiants émis par Sovrium | **Sortante** — identifiants présentés par Sovrium | | Qui est authentifié | Un appelant, auprès de votre instance | Votre instance, auprès d'un service tiers | | Où c'est déclaré | `auth.apiKeys` | `app.connections[]` | | Où c'est géré | `/_admin/api-keys` | `/_admin/connections` | Une Connexion de `type: apiKey` détient la clé de **quelqu'un d'autre** pour qu'une automatisation puisse appeler son API. Cette page traite des clés que votre propre instance émet pour qu'on puisse appeler la vôtre. Activer l'une ne dit rien de l'autre. ## Pages associées - [Sessions](/fr/docs/auth-sessions) — l'identifiant par cookie auquel les clés s'ajoutent. - [Présentation de l'API REST](/fr/docs/api-reference) — le contrat d'authentification qui régit chaque endpoint. - [Rôles & RBAC](/fr/docs/auth-roles-rbac) — les rôles dont une clé hérite. - [Gestion des utilisateurs](/fr/docs/user-management) — bannissement, levée de bannissement et changements de rôle. - [Connexions](/fr/docs/automation-connections) — les identifiants sortants, l'autre direction. - [Durcissement de la sécurité](/fr/docs/security-hardening) — déployer sereinement une surface protégée par identifiants.