Aller au contenu
Sursa Developers

POST/v1/api-keys/{key_id}/roll

Renouveler une clé API

roll_api_key

Émet une nouvelle valeur pour la clé. Les portées, les collections, les réseaux autorisés, le rôle et la date d’expiration restent les mêmes. L’ancienne valeur continue de fonctionner pendant overlap_hours heures (24 par défaut, jusqu’à 168) ou jusqu’à sa révocation anticipée avec POST /v1/api-keys/{key_id}/revoke-previous. La nouvelle valeur n’est affichée qu’une seule fois.

Authentification

Envoyez une clé API dans l’en-tête Authorization : Authorization: Bearer <clé>.

Paramètres de chemin

  • key_idintegerobligatoire

Paramètres d’en-tête

  • Idempotency-Keystring

    Clé permettant de réessayer une écriture sans risque : de 1 à 255 caractères ASCII imprimables ; un UUID v4 par opération logique est recommandé. Une nouvelle tentative avec la même clé dans les 24 heures n’exécute pas l’opération une seconde fois : elle renvoie la réponse enregistrée (statut, en-têtes et corps) avec l’en-tête Idempotency-Replayed: true. La même clé avec une méthode, un chemin, un Content-Type ou un corps différents renvoie 409 api.idempotency_mismatch ; tant que la première requête est en cours, 409 api.idempotency_in_progress avec Retry-After: 1. Après une réponse 5xx ou 429, la clé est libérée, et une nouvelle tentative exécute de nouveau l’opération. La clé est propre à l’organisation et à l’appelant (clé API, utilisateur ou clé de source personnalisée).

    length ≥ 1, length ≤ 255

  • X-View-Asstring

    Uniquement pour les clés API ayant le rôle admin. Exécute la requête avec le profil de données <profile>[:viewer|verifier|editor], par exemple employee:viewer. La clé d’installation ne peut pas utiliser cet en-tête (403).

Paramètres de cookie

  • kb_view_asstring

    Cookie du mode « View as » pour une session. POST /auth/view-as le définit et DELETE /auth/view-as le supprime.

Corps de la requête

application/json

Objet : ApiKeyRoll

  • overlap_hoursinteger

    Nombre d’heures pendant lesquelles l’ancienne valeur de la clé reste valide après le renouvellement. 0 la désactive immédiatement.

    Par défaut : 24≥ 0, ≤ 168

Réponses

200Réponse réussie

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

  • Idempotency-Replayed

    true signifie que la réponse a été rejouée à partir de celle enregistrée pour cette Idempotency-Key : l’opération ne s’est pas exécutée une seconde fois.

application/json

Objet : ApiKeyRolled

  • idintegerobligatoire
  • namestringobligatoire
  • prefixstringobligatoire

    Début de la nouvelle valeur.

  • keystringobligatoire

    Nouvelle valeur de la clé.

  • rolled_atstring (date-time)obligatoire
  • previous_prefixstringobligatoire

    Début de l’ancienne valeur.

  • previous_expires_atstring (date-time) | nullobligatoire

    Date jusqu’à laquelle l’ancienne valeur fonctionne. null signifie qu’elle ne fonctionne plus.

401Aucun identifiant n’a été envoyé (ni cookie de session ni clé API), ou la clé est introuvable.

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

403L’action n’est pas autorisée : le rôle est insuffisant, il n’y a pas d’accès à la collection ou à la fiche, la requête s’exécute en mode « View as », ou l’organisation est suspendue ou supprimée (`detail` est un objet avec `code: org_suspended | org_deleted`).

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

404L’objet n’existe pas ou ne vous est pas accessible. L’API ne confirme pas l’existence d’un objet à accès restreint.

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

422Erreur de validation : le corps ou les paramètres ne correspondent pas au schéma (`detail` est une liste d’erreurs de validation), ou la valeur d’un paramètre est hors des limites admises (`detail` est un message).

En-têtes de la réponse

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

429Trop de requêtes (`api.rate_limited`), quota de l’organisation pour la minute, le jour ou le mois épuisé (`api.quota_exceeded` ; `error.details` contient `quota`, `limit` et `reset_at`), limite de l’organisation atteinte, ou service de réponses occupé (`answers.engine_busy`). Attendez le délai indiqué dans l’en-tête `Retry-After`.

En-têtes de la réponse

  • Retry-After

    Nombre de secondes à attendre avant de réessayer la requête.

  • RateLimit-Policy

    Limites en vigueur, au format du brouillon IETF draft-ietf-httpapi-ratelimit-headers : éléments séparés par des virgules "<name>";q=<quota>;w=<window in seconds>. key est le débit de requêtes de la clé API (le quota est la rafale, la fenêtre est le temps nécessaire pour la reconstituer entièrement ; pour une session, c’est user, sans identifiants, ip) ; minute, day et month sont les quotas de l’organisation pour la minute, le jour et le mois calendaires en UTC.

  • RateLimit

    Ce qui reste de chaque limite de RateLimit-Policy : "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limite de l’entrée la plus stricte de RateLimit-Policy (celle à laquelle il reste le moins de requêtes).

  • X-RateLimit-Remaining

    Requêtes restantes au titre de la limite la plus stricte.

  • X-RateLimit-Reset

    Secondes restantes avant la réinitialisation de la limite la plus stricte.

application/json

Objet : Error

Codes d’erreur

Codes que ce point de terminaison peut renvoyer dans error.code, en plus des codes généraux communs à toutes les requêtes.

Nouvelles tentatives sans risque

Envoyez un en-tête Idempotency-Key (par exemple un UUID) avec chaque POST et PATCH. Une nouvelle tentative avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter à nouveau la requête.

Limites de débit

Les réponses portent les en-têtes RateLimit et RateLimit-Policy, ainsi que les anciens X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse 429 contient Retry-After en secondes : attendez, puis réessayez.

← api-keys · Référence de l’API