Chiavi di provisioning

Una chiave di provisioning consente al tuo backend di creare e gestire chiavi API di inferenza in modo programmatico — senza che nessuno debba accedere alla Console. Ideale per prodotti SaaS che emettono una chiave per cliente finale, per dispositivo o per job CI.

Come funziona

1. Un owner o admin crea una chiave di provisioning in Console → Chiavi di provisioning. Ha il prefisso sk-syn-prov-.
2. Il tuo backend chiama gli endpoint /api/provisioning/* con quella chiave per creare chiavi di inferenza (prefisso sk-syn-).
3. Ogni chiave di inferenza è vincolata allo stesso workspace e può avere un tetto di spesa in USD e tag metadata opachi.
4. Consegna le chiavi di inferenza ai tuoi clienti. Puoi revocarle singolarmente in qualsiasi momento — l'eliminazione di una chiave di provisioning non influisce sulle chiavi di inferenza già create.

Autenticazione

Passa la chiave di provisioning come token Bearer. Funziona solo su /api/provisioning/* — una chiave di provisioning non può effettuare chiamate di inferenza e una normale chiave di inferenza non può chiamare questi endpoint di gestione (entrambe restituiscono 401 wrong_key_kind).

Authorization: Bearer sk-syn-prov-...

Creare una chiave di inferenza

POST /api/provisioning/keys

curl https://synthorai.io/api/provisioning/keys \
  -H "Authorization: Bearer sk-syn-prov-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Device abc-123",
    "quota": 5.0,
    "allowed_models": "claude-haiku-4-5",
    "metadata": { "tenant_id": "acme", "device_id": "abc-123" }
  }'

import requests

resp = requests.post(
    "https://synthorai.io/api/provisioning/keys",
    headers={"Authorization": "Bearer sk-syn-prov-..."},
    json={
        "name": "Device abc-123",
        "quota": 5.0,
        "allowed_models": "claude-haiku-4-5",
        "metadata": {"tenant_id": "acme", "device_id": "abc-123"},
    },
)
inference_key = resp.json()["key"]  # full key — shown only once

La risposta restituisce la chiave completa nel campo key e la mostra una sola volta. Conservala subito — non potrà essere recuperata in seguito.

{
  "id": 42,
  "key": "sk-syn-d4f0...e91b",
  "key_prefix": "sk-syn-d4f0...",
  "name": "Device abc-123",
  "kind": "inference",
  "created_via": "provisioning_api",
  "parent_provisioning_id": 7,
  "workspace_id": 11,
  "quota_usd": 5.0,
  "unlimited_quota": false,
  "allowed_models": "claude-haiku-4-5",
  "metadata": { "tenant_id": "acme", "device_id": "abc-123" },
  "created_at": "2026-06-01T12:00:00Z"
}

Elencare le chiavi di inferenza

GET /api/provisioning/keys

Elenca tutte le chiavi di inferenza del workspace. Filtra per qualsiasi campo metadata con ?metadata.<key>=<value>; più filtri vengono combinati in AND.

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

# only keys tagged tenant_id=acme
curl "https://synthorai.io/api/provisioning/keys?metadata.tenant_id=acme" \
  -H "Authorization: Bearer sk-syn-prov-..."

Recuperare, aggiornare ed eliminare

Indirizza una singola chiave di inferenza tramite il suo campo numerico id:

• GET /api/provisioning/keys/{id} — recupera una singola chiave.
• PATCH /api/provisioning/keys/{id} — aggiorna name, quota, status, allowed_models, ip_whitelist, expires_at, include_byok_in_limit, o metadata. Il campo kind e i campi di lineage non possono essere modificati.
• DELETE /api/provisioning/keys/{id} — revoca una chiave. Effetto immediato.

# disable a key (status 2 = disabled)
curl -X PATCH https://synthorai.io/api/provisioning/keys/42 \
  -H "Authorization: Bearer sk-syn-prov-..." \
  -H "Content-Type: application/json" \
  -d '{ "status": 2 }'

# delete a key
curl -X DELETE https://synthorai.io/api/provisioning/keys/42 \
  -H "Authorization: Bearer sk-syn-prov-..."

Quote e controllo della spesa

quota è un tetto in USD per chiave di inferenza. L'utilizzo viene conteggiato dopo ogni richiesta, quindi in caso di alta concorrenza una chiave può superare leggermente il suo tetto entro una breve finestra di regolamento — dimensiona i tetti con un piccolo margine per i modelli costosi. Leggi la spesa corrente di una chiave da used_usd nelle risposte di elenco / recupero.

Stai dimensionando limiti in USD per chiave? Il LLM API cost calculator converte il volume di token previsto di un cliente in una spesa mensile che puoi impostare come quota.