Chiavi di amministrazione

Con una chiave di amministrazione gestisci un workspace dal tuo codice: crei le chiavi di inferenza che usano i tuoi clienti o dispositivi, ne fissi i limiti e leggi utilizzo, log e impostazioni. Non può chiamare un modello.

Creare una chiave di amministrazione

1. Nella console apri Chiavi API › Chiavi di amministrazione e scegli Crea chiave di amministrazione. Possono farlo gli amministratori e il proprietario del workspace.
2. Scegli a chi appartiene la chiave e quali ambiti ha.
3. Copia la chiave. Inizia con sk-syn-admin- e viene mostrata una sola volta.

Ambiti

Ogni ambito apre una parte dell’API di gestione. Un ambito di scrittura include quello di lettura corrispondente. Se la chiave non ha l’ambito richiesto, la richiesta riceve 403 insufficient_scope.

A chi appartiene una chiave

• A te. Se lasci il workspace, la chiave viene disattivata. Se resti ma non sei più amministratore, le richieste ricevono 403 key_creator_not_authorized.
• Al workspace. La chiave continua a funzionare anche se chi l’ha creata lascia il workspace o cambia ruolo. Usala per CI e integrazioni. Quando chi l’ha creata se ne va, la chiave passa al proprietario del workspace insieme alle chiavi di inferenza create con essa, e continuano tutte a funzionare.

Lo scegli quando crei la chiave e non puoi cambiarlo in seguito.

Autenticazione

Invia la chiave come token Bearer. Una chiave di amministrazione funziona solo sull’API di gestione: gli endpoint dei modelli sotto /v1/ la rifiutano, e l’API di gestione rifiuta una chiave di inferenza (sk-syn-) con 401 wrong_key_kind.

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

Creare una chiave di inferenza

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 risposta contiene la chiave completa nel campo key, una sola volta. Salvala subito: le letture successive restituiscono solo 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..." }
}

Per ripetere una creazione senza rischi, invia un header Idempotency-Key. Una richiesta ripetuta con lo stesso valore restituisce la prima risposta, senza il segreto. La chiave restituisce quella risposta per 24 ore, anche se nel frattempo la risorsa è stata eliminata: per ricrearla, usa una chiave nuova.

Elencare e filtrare le chiavi

GET /api/v1/keys

Filtra per qualsiasi campo dei metadati con ?metadata.<name>=<value>. I risultati sono paginati: per la pagina successiva passa meta.next_cursor come cursor.

# 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-..."

Leggere, modificare, ruotare ed eliminare

• GET /api/v1/keys/{id} restituisce una chiave.
• PATCH /api/v1/keys/{id} modifica solo i campi che invii. "enabled": false blocca la chiave senza eliminarla.
• POST /api/v1/keys/{id}/rotate assegna alla chiave un nuovo segreto. Il vecchio smette subito di funzionare.
• DELETE /api/v1/keys/{id} elimina la chiave. Le richieste che la usano ricevono subito 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-..."

Una chiave di amministrazione agisce per un solo membro: chi l’ha creata o, se la chiave è del workspace e chi l’ha creata se n’è andato, il proprietario. Può modificare, ruotare ed eliminare solo le chiavi di quel membro, comprese quelle che ha creato; sulla chiave di un altro membro la risposta è 403 not_key_creator, anche con la chiave di amministrazione del proprietario. Su un’istanza dedicata qualsiasi chiave di amministrazione del workspace può gestire le chiavi di tutti i membri, come gli amministratori nella console. Una chiave disattivata da un amministratore può essere riattivata solo da un amministratore: chiunque altro riceve 403 disabled_by_admin.

Limiti e spesa

limit_usd è quanto la chiave può spendere, used_usd quanto ha già speso. Raggiunto il limite, status diventa limit_reached e le richieste vengono rifiutate finché non alzi il limite o il periodo non si azzera.

Devi decidere il limite di spesa di ogni chiave? Il calcolatore dei costi delle API LLM trasforma il volume di token previsto per un cliente in una cifra mensile da impostare come limit_usd.

Errori

Gli errori seguono il formato dell’API di gestione: error.code indica il motivo e error.message cosa fare. Su /api/provisioning/keys lo stesso codice arriva in error.type. Questi sono i codici specifici delle chiavi di amministrazione e degli endpoint delle chiavi:

Chiavi di provisioning e /api/provisioning

Le chiavi emesse prima delle chiavi di amministrazione (sk-syn-prov-) continuano a funzionare, con gli ambiti keys.read e keys.write. Il vecchio indirizzo /api/provisioning/keys risponde ancora, con i suoi nomi di campo (quota, status). Per le nuove integrazioni usa /api/v1/keys.

L’API di gestione copre anche la fatturazione, il registro delle richieste, i prompt e le impostazioni del workspace. Vedi la panoramica dell’API e il documento OpenAPI.