Clés de l'API IA

Une clé authentifie un appel et en fixe les limites. Cette ressource gère les clés de votre projet IA, y compris celle qui fait la requête. Seule une empreinte du secret est conservée : une clé n'est donc affichée en entier qu'une seule fois, dans la réponse qui la crée.

Points d'accès

<key_id> est un identifiant de clé, préfixé papi_. current est un mot réservé à cet emplacement : il désigne la clé avec laquelle la requête est faite.

L'objet api_key

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

Lister les clés

GET /v1/ai/key/list renvoie les clés de votre projet, de la plus récente à la plus ancienne, sans les clés révoquées. Il accepte limit et offset.

curl https://api.ultineo.com/v1/ai/key/list \
  -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": 1789209200,
        "created_by": "cons_8e2b45a10c9df7631b4a",
        "created_at": 1788414400,
        "updated_at": 1789209200
      }
    ],
    "total": 1
  }
}

Lire la clé appelante

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

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

GET /v1/ai/key/detail/<key_id> lit de la même façon n'importe quelle clé de votre projet. Une clé d'un autre projet, ou une clé révoquée, renvoie 404 et API key not found.

Créer une clé

POST /v1/ai/key/create crée une nouvelle clé pour le même projet.

curl -X POST https://api.ultineo.com/v1/ai/key/create \
  -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_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": 1789209800,
    "updated_at": 1789209800,
    "key": "sk-project-7Qd1xR0mZ8pKvT3sLb…"
  }
}

Important — key figure dans cette seule réponse et nulle part ailleurs. Conservez-la avant d'abandonner la réponse. Un secret perdu ne peut pas être récupéré, seulement remplacé par une nouvelle clé.

Une clé ne peut jamais accorder plus que la clé qui l'a créée. Demander un droit que votre propre clé ne détient pas est refusé, et non réduit en silence.

Important — Comme omettre scope revient à ["*"], une clé qui ne détient pas elle-même * doit envoyer une liste scope explicite : l'omettre donne un 403, même si le paramètre est facultatif.

Un droit qui ne respecte pas la grammaire des droits (*, <ressource>:*, <ressource>:read ou <ressource>:write) est refusé avec 422 et un message qui rappelle cette grammaire.

Renommer, suspendre ou réactiver une clé

PATCH /v1/ai/key/detail/<key_id> modifie le nom d'une clé, son statut, ou les deux.

curl -X PATCH https://api.ultineo.com/v1/ai/key/detail/papi_b6294fc0e178ad35c9b2 \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "suspended" }'

La réponse est la clé mise à jour. Une clé suspendue répond 403 sur tous les chemins IA jusqu'à ce que vous la réactiviez.

Révoquer une clé

DELETE /v1/ai/key/detail/<key_id> révoque la clé immédiatement. Tout appel fait ensuite avec elle répond 403 et The API key doesn't have permissions to perform the request., la même réponse qu'une clé inconnue. Une clé révoquée ne peut pas être réactivée.

curl -X DELETE https://api.ultineo.com/v1/ai/key/detail/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 avec 422 et Cannot revoke the API key currently in use. : une rotation ne peut donc pas vous bloquer à mi-chemin. Créez la nouvelle clé, faites passer votre trafic dessus, puis révoquez l'ancienne avec la nouvelle.