Chaves de administração

Com uma chave de administração, seu código gerencia um workspace: cria e limita as chaves de inferência usadas por seus clientes ou dispositivos e lê uso, logs e configurações. Ela não chama modelos.

Criar uma chave de administração

1. No console, abra Chaves de API › Chaves de administração e escolha Criar chave de administração. Só administradores e o proprietário do workspace podem fazer isso.
2. Escolha a quem a chave pertence e quais escopos ela terá.
3. Copie a chave. Ela começa com sk-syn-admin- e só é exibida uma vez.

Escopos

Cada escopo dá acesso a uma parte da API de gerenciamento. Um escopo de escrita inclui o de leitura correspondente. Se a chave não tiver o escopo exigido, a requisição retorna 403 insufficient_scope.

A quem a chave pertence

• Você. A chave é desativada se você sair do workspace. Se você continuar nele, mas deixar de ser administrador, as requisições retornam 403 key_creator_not_authorized.
• O workspace. A chave continua funcionando depois que quem a criou sai ou muda de função. Use esta opção para CI e integrações. Quando quem a criou sai, a chave passa para o proprietário do workspace junto com as chaves de inferência criadas com ela, e todas continuam funcionando.

Você escolhe ao criar a chave. Não é possível mudar depois.

Autenticação

Envie a chave como Bearer token. Uma chave de administração só funciona na API de gerenciamento: os endpoints de modelos em /v1/ a recusam, e a API de gerenciamento recusa uma chave de inferência (sk-syn-) com 401 wrong_key_kind.

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

Criar uma chave de inferência

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

A resposta traz a chave completa em key, uma única vez. Guarde-a na hora: as leituras seguintes retornam apenas 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..." }
}

Para repetir uma criação com segurança, envie o cabeçalho Idempotency-Key. Uma repetição com o mesmo valor retorna a primeira resposta, sem o segredo. A chave retorna essa resposta por 24 horas, mesmo que o recurso tenha sido excluído nesse meio-tempo: para criá-lo de novo, use uma chave nova.

Listar e filtrar chaves

GET /api/v1/keys

Filtre por qualquer campo de metadados com ?metadata.<name>=<value>. Os resultados são paginados: para a página seguinte, passe meta.next_cursor como 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-..."

Ler, alterar, rotacionar e excluir

• GET /api/v1/keys/{id} retorna uma chave.
• PATCH /api/v1/keys/{id} altera apenas os campos enviados. "enabled": false desativa a chave sem excluí-la.
• POST /api/v1/keys/{id}/rotate gera um novo segredo para a chave. O antigo para de funcionar na hora.
• DELETE /api/v1/keys/{id} exclui a chave. As requisições que a usam passam a retornar 401 na hora.

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

Uma chave de administração age em nome de um único membro: quem a criou ou, se a chave for do workspace e quem a criou tiver saído, o proprietário. Ela só altera, rotaciona e exclui as chaves desse membro, incluindo as que ela mesma criou; na chave de outro membro, a requisição retorna 403 not_key_creator, mesmo com a chave de administração do proprietário. Em uma instância dedicada, qualquer chave de administração do workspace pode gerenciar as chaves de todos os membros, como os administradores fazem no console. Uma chave desativada por um administrador só pode ser reativada por um administrador: qualquer outra pessoa recebe 403 disabled_by_admin.

Limites e gastos

limit_usd é quanto a chave pode gastar e used_usd é quanto ela já gastou. Ao atingir o limite, status passa a limit_reached e as requisições são recusadas até você aumentar o limite ou o período reiniciar.

Vai definir limites de gasto por chave? A calculadora de custos de API de LLM converte o volume de tokens esperado de um cliente em um valor mensal que você pode usar como limit_usd.

Erros

Os erros vêm no formato da API de gerenciamento: error.code indica o motivo e error.message, o que fazer. Em /api/provisioning/keys, o mesmo código vem em error.type. Estes são os códigos específicos das chaves de administração e dos endpoints de chaves:

Chaves de provisionamento e /api/provisioning

As chaves emitidas antes das chaves de administração (sk-syn-prov-) continuam funcionando, com os escopos keys.read e keys.write. O endereço anterior, /api/provisioning/keys, continua no ar com seus próprios nomes de campo (quota, status). Em integrações novas, use /api/v1/keys.

A API de gerenciamento também cobre cobrança, o log de requisições, prompts e as configurações do workspace. Veja a visão geral da API e o documento OpenAPI.