Clés API

Une clé est ce qui authentifie un appel et ce qui en limite la portée. Cette ressource gère les clés du projet, y compris celle qui effectue la requête. Le secret brut n'est jamais conservé — seule son empreinte SHA-256 l'est — de sorte qu'une clé n'est affichée en entier qu'une seule fois, dans la réponse qui la crée.

Pour créer votre première clé depuis l'espace de travail, voir Clés API du projet.

Les appels

<key_id> est un identifiant de clé, préfixé papi_. current est un mot réservé à cette position et désigne la clé avec laquelle la requête est authentifiée.

L'objet clé API

Le secret lui-même n'apparaît dans aucune réponse de lecture. key_preview en est la seule partie que l'API vous montrera à nouveau.

Lister les clés

GET /v1/key renvoie les clés du projet, les plus récentes d'abord.

curl https://api.think.ultineo.com/v1/key \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [
      {
        "id": "papi_4e07c1b8a35df926104c",
        "object": "api_key",
        "name": "Production backend",
        "key_preview": "sk-project-...a7e1",
        "scope": ["reasoning:*", "app:read", "usage:read"],
        "status": "activated",
        "expires_at": null,
        "last_used_at": 1754209200,
        "created_by": "cons_8e2b45a10c9df7631b4a",
        "created_at": 1751414400,
        "updated_at": 1754209200
      }
    ],
    "total": 1
  }
}

Consulter la clé appelante

GET /v1/key/current est le moyen le plus rapide de savoir ce que votre clé peut faire, sans connaître son identifiant.

curl https://api.think.ultineo.com/v1/key/current \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

Une clé d'un autre projet donne 404 et API key not found.

Créer une clé

POST /v1/key émet une nouvelle clé pour le même projet.

curl -X POST https://api.think.ultineo.com/v1/key \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly batch",
    "scope": ["reasoning:read", "reasoning:write", "usage:read"]
  }'

{
  "code": 201,
  "title": "Created",
  "response": {
    "id": "papi_b6294fc0e178ad35c9b2",
    "object": "api_key",
    "name": "Nightly batch",
    "key": "sk-project-7Qd1xR0mZ8pKvT3sLb...",
    "key_preview": "sk-project-...Lb92",
    "scope": ["reasoning:read", "reasoning:write", "usage:read"],
    "status": "activated",
    "expires_at": null,
    "last_used_at": null,
    "created_by": "cons_8e2b45a10c9df7631b4a",
    "created_at": 1754209800,
    "updated_at": 1754209800
  }
}

Important — key est présent dans cette seule réponse et nulle part ailleurs. Conservez-le avant de jeter la réponse. Un secret perdu ne peut pas être retrouvé, seulement remplacé en créant une autre clé.

Une clé ne peut jamais accorder plus que la clé qui l'a créée. Demander une portée que l'appelant ne détient pas lui-même est refusé plutôt que silencieusement réduit.

Important — Rien n'est restreint à votre place, et cela vaut aussi pour la valeur par défaut. Puisque omettre scope signifie ["*"], une clé qui ne détient pas elle-même * doit envoyer un tableau scope explicite : ne pas transmettre le paramètre donne un 403, bien qu'il ne soit pas obligatoire.

Révoquer une clé

DELETE /v1/key/<key_id> révoque la clé immédiatement. Tout appel effectué avec elle par la suite répond 403 et The API key doesn't have permissions to perform the request. — la même réponse que reçoit une clé inconnue. Le 401 est réservé à une clé qui avait une échéance et l'a atteinte. Voir Codes d'erreur.

curl -X DELETE https://api.think.ultineo.com/v1/key/papi_b6294fc0e178ad35c9b2 \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "deleted": true,
    "id": "papi_b6294fc0e178ad35c9b2"
  }
}

La clé avec laquelle vous appelez est refusée par un 422 et Cannot revoke the API key currently in use., de sorte qu'une rotation ne peut pas vous enfermer dehors à mi-chemin. Créez la clé de remplacement, basculez votre trafic dessus, puis révoquez l'ancienne clé avec la nouvelle.