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.

auth:
  strategies:
    - type: emailAndPassword
  apiKeys: true

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.

curl -H "x-api-key: $SOVRIUM_API_KEY" \
  http://localhost:3000/api/tables/notes/records

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.

Créer une clé depuis une session de navigateur authentifiée :

curl -X POST http://localhost:3000/api/auth/api-key/create \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ "name": "Nightly backup job" }'

{
  "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.

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.

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.

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 — l'identifiant par cookie auquel les clés s'ajoutent.
• Présentation de l'API REST — le contrat d'authentification qui régit chaque endpoint.
• Rôles & RBAC — les rôles dont une clé hérite.
• Gestion des utilisateurs — bannissement, levée de bannissement et changements de rôle.
• Connexions — les identifiants sortants, l'autre direction.
• Durcissement de la sécurité — déployer sereinement une surface protégée par identifiants.