Chaves de provisioning

Uma chave de provisioning permite que seu backend crie e gerencie chaves de API de inferência de forma programática — sem que ninguém faça login no Console. Ideal para produtos SaaS que emitem uma chave por cliente final, por dispositivo ou por job de CI.

Como funciona

1. Um owner ou admin cria uma chave de provisioning em Console → Chaves de provisioning. Ela tem o prefixo sk-syn-prov-.
2. Seu backend chama os /api/provisioning/* endpoints com essa chave para criar chaves de inferência (prefixo sk-syn-).
3. Cada chave de inferência é limitada ao mesmo workspace e pode levar um limite de gasto em USD e metadata opacos.
4. Entregue as chaves de inferência aos seus clientes. Revogue qualquer uma delas individualmente a qualquer momento — excluir uma chave de provisioning não afeta as chaves de inferência que ela já criou.

Autenticação

Passe a chave de provisioning como Bearer token. Funciona apenas em /api/provisioning/* — uma chave de provisioning não pode fazer chamadas de inferência, e uma chave de inferência normal não pode chamar esses endpoints de gestão (ambas retornam 401 wrong_key_kind).

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

Criar uma chave de inferência

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

A resposta retorna a chave completa no key campo exatamente uma vez. Armazene-a imediatamente — não pode ser recuperada posteriormente.

{
  "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"
}

Listar chaves de inferência

GET /api/provisioning/keys

Lista todas as chaves de inferência do workspace. Filtre por qualquer campo de metadados com ?metadata.<key>=<value>; vários filtros são combinados com 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-..."

Recuperar, atualizar e excluir

Enderece uma única chave de inferência pelo seu id:

• GET /api/provisioning/keys/{id} — obter uma chave.
• PATCH /api/provisioning/keys/{id} — atualizar name, quota, status, allowed_models, ip_whitelist, expires_at, include_byok_in_limit, ou metadata. Os campos kind e de linhagem não podem ser alterados.
• DELETE /api/provisioning/keys/{id} — revogar uma chave. Efeito imediato.

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

Cotas e controle de gastos

quota é um limite em USD por chave de inferência. O uso é medido após cada solicitação, então uma chave pode exceder ligeiramente seu limite dentro de uma curta janela de liquidação sob alta concorrência — dimensione os limites com uma pequena margem para modelos de alto valor. Leia o gasto atual de uma chave em used_usd nas respostas de listagem / recuperação.

Está dimensionando limites em USD por chave? A LLM API cost calculator converte o volume de tokens esperado de um cliente em um gasto mensal que você pode definir como quota.