Clés d’administration

Une clé d’administration gère un espace de travail depuis votre code. Elle crée et plafonne les clés d’inférence qu’utilisent vos clients ou vos appareils, et lit l’usage, les journaux et les paramètres. Elle ne peut pas appeler de modèle.

Créer une clé d’administration

1. Dans la console, ouvrez Clés API › Clés d’administration, puis cliquez sur Créer une clé d’administration. Seuls les admins et le propriétaire de l’espace de travail y ont accès.
2. Choisissez à qui la clé appartient et quelles portées elle reçoit.
3. Copiez la clé. Elle commence par sk-syn-admin- et ne s’affiche qu’une fois.

Portées

Chaque portée ouvre une partie de l’API de gestion. Une portée d’écriture inclut la portée de lecture correspondante. Si la clé n’a pas la portée requise, la requête renvoie 403 insufficient_scope.

À qui appartient une clé

• Vous. La clé est désactivée si vous quittez l’espace de travail. Si vous y restez sans être admin, les requêtes renvoient 403 key_creator_not_authorized.
• L’espace de travail. La clé continue de fonctionner si la personne qui l’a créée part ou change de rôle. À utiliser pour la CI et les intégrations. Si cette personne part, la clé passe au propriétaire de l’espace de travail avec les clés d’inférence créées grâce à elle, et toutes continuent de fonctionner.

Ce choix se fait à la création de la clé et ne peut plus être modifié ensuite.

Authentification

Envoyez la clé comme jeton Bearer. Une clé d’administration ne fonctionne que sur l’API de gestion : les endpoints de modèles sous /v1/ la refusent, et l’API de gestion refuse une clé d’inférence (sk-syn-) avec 401 wrong_key_kind.

Authorization: Bearer sk-syn-admin-...

Créer une clé d’inférence

POST /api/v1/keys

curl https://synthorai.io/api/v1/keys \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: device-abc-123" \
  -d '{
    "name": "Device abc-123",
    "limit_usd": 5.0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/v1/keys",
    headers={
        "Authorization": "Bearer sk-syn-admin-...",
        "Idempotency-Key": "device-abc-123",
    },
    json={
        "name": "Device abc-123",
        "limit_usd": 5.0,
        "limit_reset": "monthly",
        "allowed_models": ["claude-haiku-4-5"],
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["data"]["key"]  # full key - shown only once

La réponse contient la clé complète dans key, une seule fois. Enregistrez-la tout de suite : les lectures suivantes ne renvoient que key_prefix.

{
  "data": {
    "id": 42,
    "key": "sk-syn-d4f0...e91b",
    "key_prefix": "sk-syn-d4f0...",
    "name": "Device abc-123",
    "enabled": true,
    "status": "enabled",
    "limit_usd": 5.0,
    "used_usd": 0,
    "limit_reset": "monthly",
    "allowed_models": ["claude-haiku-4-5"],
    "ip_allowlist": [],
    "expires_at": null,
    "include_byok_in_limit": true,
    "rate_limit": { "rpm": 0, "tpm": 0 },
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
    "created_via": "provisioning_api",
    "created_at": "2026-10-01T12:00:00Z"
  },
  "meta": { "request_id": "01a1..." }
}

Pour relancer une création sans risque de doublon, envoyez un en-tête Idempotency-Key. Une nouvelle requête avec la même valeur renvoie la première réponse, sans le secret. La clé renvoie cette réponse pendant 24 heures, même si la ressource a été supprimée entre-temps : pour la recréer, utilisez une nouvelle clé.

Lister et filtrer les clés

GET /api/v1/keys

Filtrez sur n’importe quel champ de métadonnées avec ?metadata.<name>=<value>. Les résultats sont paginés : passez meta.next_cursor dans cursor pour obtenir la page suivante.

# all keys
curl https://synthorai.io/api/v1/keys \
  -H "Authorization: Bearer sk-syn-admin-..."

# only keys tagged tenant_id=acme, 50 at a time
curl "https://synthorai.io/api/v1/keys?metadata.tenant_id=acme&limit=50" \
  -H "Authorization: Bearer sk-syn-admin-..."

Lire, modifier, renouveler et supprimer

• GET /api/v1/keys/{id} renvoie une clé.
• PATCH /api/v1/keys/{id} ne modifie que les champs envoyés. "enabled": false arrête la clé sans la supprimer.
• POST /api/v1/keys/{id}/rotate donne un nouveau secret à la clé. L’ancien cesse aussitôt de fonctionner.
• DELETE /api/v1/keys/{id} supprime la clé. Les requêtes qui l’utilisent renvoient aussitôt 401.

# stop a key without deleting it
curl -X PATCH https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# give it a new secret
curl -X POST https://synthorai.io/api/v1/keys/42/rotate \
  -H "Authorization: Bearer sk-syn-admin-..."

# delete it
curl -X DELETE https://synthorai.io/api/v1/keys/42 \
  -H "Authorization: Bearer sk-syn-admin-..."

Une clé d’administration agit pour un seul membre : la personne qui l’a créée, ou le propriétaire si la clé appartient à l’espace de travail et que cette personne est partie. Elle ne peut modifier, renouveler et supprimer que les clés de ce membre, y compris celles qu’elle a créées ; pour la clé d’un autre membre, la requête renvoie 403 not_key_creator, même avec la clé d’administration du propriétaire. Sur une instance dédiée, toute clé d’administration de l’espace de travail peut gérer les clés de tous les membres, comme les admins dans la console. Une clé désactivée par un admin ne peut être réactivée que par un admin : pour toute autre personne, la requête renvoie 403 disabled_by_admin.

Plafonds et dépenses

limit_usd est ce que la clé peut dépenser, used_usd ce qu’elle a déjà dépensé. Une fois le plafond atteint, status passe à limit_reached et les requêtes sont refusées jusqu’à ce que vous releviez le plafond ou que la période reparte de zéro.

Vous cherchez quel plafond de dépense fixer par clé ? Le calculateur de coûts d’API LLM convertit le volume de tokens attendu d’un client en un montant mensuel, à reprendre dans limit_usd.

Erreurs

Les erreurs suivent le format de l’API de gestion : error.code donne la cause et error.message ce qu’il faut faire. Sur /api/provisioning/keys, le même code arrive dans error.type. Voici les codes propres aux clés d’administration et aux endpoints des clés :

Clés de provisioning et /api/provisioning

Les clés émises avant les clés d’administration (sk-syn-prov-) continuent de fonctionner, avec les portées keys.read et keys.write. L’ancienne adresse /api/provisioning/keys reste servie, avec ses propres noms de champs (quota, status). Pour une nouvelle intégration, utilisez /api/v1/keys.

L’API de gestion couvre aussi la facturation, le journal des requêtes, les prompts et les paramètres de l’espace de travail. Consultez la présentation de l’API et le document OpenAPI.