Clés API et portées

Chaque requête adressée à l’API Sursa est faite avec une clé API de votre organisation. Une clé appartient à l’organisation, pas à une personne : elle continue de fonctionner quand le salarié qui l’a créée s’en va, et ce qu’elle peut faire est défini sur la clé elle-même.

Ce qu’une clé a le droit de faire

Trois réglages d’une clé déterminent ce qu’une requête faite avec elle peut voir et modifier. Chacun ne fait que restreindre les autres.

Réglage	Ce qu’il contrôle
Rôle	`admin`, `editor`, `verifier` ou `viewer`, les mêmes rôles que ceux des personnes. La clé peut faire ce que peut faire un utilisateur doté de ce rôle.
Portées	Les parties de l’API que la clé peut appeler, par exemple `cards:read` ou `webhooks:manage`. Voir Portées des clés.
Profil de données	Facultatif. Limite la clé aux catégories de connaissances que le profil autorise, comme un utilisateur doté de ce profil.

Une clé peut aussi être limitée à certaines collections et recevoir une date d’expiration. Une requête qui sort de ces limites échoue : une portée manquante renvoie 403 avec le code api_keys.scope, et un objet que la clé ne peut pas voir renvoie 404, exactement comme s’il n’existait pas.

Donnez à chaque intégration sa propre clé, avec le rôle et les portées les plus restreints possible. Un job de synchronisation qui ne fait qu’écrire des documents n’a pas besoin de admin ; un job qui produit des rapports n’a pas besoin de portées d’écriture.

Créer une clé

Un administrateur de l’organisation crée les clés dans Sursa sous Administration → API keys, ou avec POST /v1/api-keys en utilisant une clé ou une session dotée du rôle admin :

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

La réponse contient la valeur de la clé dans key. Elle n’est affichée qu’une fois : Sursa n’en conserve qu’une empreinte et ne peut pas l’afficher de nouveau. Une clé se présente sous la forme kb_ suivi de 43 caractères ; les premiers caractères (prefix) apparaissent dans la liste des clés pour vous permettre de les distinguer.

Sans scopes, la clé reçoit les portées de son rôle. Passez scopes pour la restreindre davantage. Sans expires_at, la clé n’expire pas.

Garder les clés secrètes

Conservez les clés dans un gestionnaire de secrets ou dans des variables d’environnement de votre service, jamais dans le code source.
N’utilisez les clés que depuis vos serveurs. Sursa accepte les requêtes des navigateurs (CORS est ouvert), mais une clé placée dans une page web est visible de toute personne qui l’ouvre.
N’envoyez jamais une clé dans une URL. Envoyez-la uniquement dans l’en-tête Authorization.
Si une clé fuite, révoquez-la immédiatement et créez-en une nouvelle.

Vérifier une clé

GET /v1/me renvoie la clé, son rôle, ses portées effectives, son profil de données, son expiration et sa limite de débit. Ce point de terminaison fonctionne avec toute clé valide, quelles que soient ses portées : utilisez-le comme test de connexion de votre intégration et pour analyser un 403.

Renouveler une clé

Le renouvellement remplace une clé sans arrêter l’intégration. Le plus rapide est de renouveler la clé elle-même : POST /v1/api-keys/{key_id}/roll émet une nouvelle valeur pour la même clé, avec le même rôle, les mêmes portées, les mêmes collections et la même date d’expiration. L’ancienne valeur continue de fonctionner pendant overlap_hours (24 heures par défaut, jusqu’à 168) : vous pouvez donc déployer la nouvelle valeur entre-temps ; POST /v1/api-keys/{key_id}/revoke-previous met fin au chevauchement plus tôt.

Pour remplacer plutôt une clé par une autre :

Créez une nouvelle clé avec le même rôle, les mêmes portées et le même profil de données.
Déployez la nouvelle clé dans votre intégration.
Surveillez l’ancienne clé dans Administration → API keys (ou last_used dans GET /v1/api-keys) jusqu’à ce qu’elle ne soit plus utilisée.
Révoquez l’ancienne clé.

Fixez une date d’expiration sur les clés et renouvelez-les avant cette date. Sursa prévient les administrateurs de l’organisation avant l’expiration d’une clé ; une clé expirée renvoie 401 avec le code api_keys.expired.

Révoquer une clé

Révoquez une clé sous Administration → API keys ou avec DELETE /v1/api-keys/{key_id}. La révocation prend effet en quelques secondes sur tous les serveurs de l’API. Les requêtes faites avec une clé révoquée renvoient 401 avec le code auth.not_authenticated.

Clés d’une source personnalisée

Une source personnalisée a son propre type de clé. Cette clé commence par kbsrc_, ne peut qu’écrire des documents dans cette seule source et ne peut rien lire ni rechercher. C’est la clé la plus sûre à confier à une plateforme d’intégration comme Zapier. Créez-la sur la page de la source, sous API keys, ou avec POST /v1/sources/{source_id}/push-keys.

Quand les clés ne sont pas disponibles

Les clés API font partie de l’offre de l’organisation. Si l’offre ne les inclut pas, la création d’une clé comme toute requête faite avec une clé renvoient 403 avec le code api_keys.feature_disabled.