Saltar para o conteúdo principal
Quando você cria ou lê uma chave de API através do console ou da REST API, o gateway retorna um objeto token — o registro JSON que contém a identidade de uma chave, seus limites e os dois anexos de política que governam seu tráfego. Esta página é a referência campo a campo desse objeto: o que cada campo significa, seu tipo, e os valores sentinela (0, -1) que carregam significado especial. Para o porquê por trás desses campos — o modelo de menor agência — comece em Visão geral de chaves com escopo. Esta página é a tabela de consulta que você mantém aberta enquanto scripta a criação de chaves.

​
1. A referência do objeto token de relance

Uma chave recém-criada para um agente sumarizador agendado se parece com isto: 
{
  "id": 4812,
  "name": "support-summarizer-prod",
  "status": 1,
  "key": "sk-orca-a1b2****yz90",
  "created_time": 1733616000,
  "accessed_time": 1733702400,
  "expired_time": -1,
  "unlimited_quota": false,
  "remain_quota": 500000,
  "used_quota": 12340,
  "model_limits_enabled": true,
  "model_limits": "openai/gpt-4o-mini",
  "credit_limit_usd": 25,
  "allow_ips": "203.0.113.7",
  "environment": "prod",
  "guardrail_id": 17,
  "firewall_policy_id": 9,
  "is_firewall_gateway": false,
  "group": "default"
}
O campo key é mascarado em cada leitura — você vê o prefixo de marca e os últimos quatro caracteres, nunca o segredo completo. O plaintext é mostrado uma vez, na criação. Veja Mascaramento de chave.

​
2. Campos de identidade & ciclo de vida

Estes descrevem qual chave é esta e onde ela está em seu ciclo de vida.
O identificador numérico estável da chave. Use-o para endereçar a chave em chamadas de update e delete. Somente leitura.
Um rótulo humano para a chave, mostrado no console e nos logs. Nomeie as chaves segundo o agente que as segura — uma chave, um agente.
Estado habilitado / desabilitado. 1 significa ativa; uma chave desabilitada é rejeitada na auth sem ser deletada, então você pode pausar uma chave e re-habilitá-la.
O segredo ao portador, retornado mascarado (sk-orca-…****…). O valor completo é mostrado apenas uma vez, na criação. Trate-o como uma senha.
Timestamps Unix (segundos) para quando a chave foi cunhada e quando ela serviu uma requisição pela última vez. accessed_time é seu sinal de uma chave obsoleta ou não usada que vale a pena revogar.
Expiração absoluta como um timestamp Unix. O sentinela -1 significa que a chave nunca expira. Defina um timestamp real para fazer uma chave autoexpirar — o padrão certo para runs de CI e agentes efêmeros. Veja Chaves expiráveis.

​
3. Campos de gasto & cota

Estes limitam quanto uma chave pode consumir antes de parar de funcionar.
CampoTipoSignificado
credit_limit_usdnumberLimite de gasto vitalício em USD. 0 = ilimitado.
unlimited_quotabooleanQuando true, a chave não é medida contra um saldo de cota.
remain_quotanumberCota restante na chave.
used_quotanumberCota consumida até agora.
Uma chave com credit_limit_usd: 0 e unlimited_quota: true e expired_time: -1 não tem teto de gasto e nunca expira — o pior raio de explosão se ela vazar. Veja ilimitada vs limitada para quando uma chave sem limite é justificada.

​
4. Campos de alcance & escopo

Estes limitam o que a chave pode alcançar — quais modelos, de quais endereços.
model_limits é a lista de modelos que a chave pode chamar; model_limits_enabled é o interruptor liga/desliga. Com o limite habilitado, uma chamada a qualquer modelo fora da lista é rejeitada antes de sair do gateway — o agente não pode trocar para um modelo mais caro ou mais capaz. Veja Limites de modelo.
Uma lista de permissão de IP / CIDR, uma entrada por linha. Uma requisição apresentando a chave de qualquer endereço não listado é rejeitada na camada de auth; um valor vazio significa que todos os endereços são permitidos. Veja Lista de permissão de IP.
Um rótulo de deployment de forma livre (prod, staging, dev, ou qualquer coisa que você escolher) para organizar chaves e filtrar logs. Puramente organizacional — não muda o enforcement. Veja Ambientes.
O grupo de roteamento através do qual a chave resolve modelos. Deixe-o no padrão do workspace a menos que você tenha recebido um grupo específico.

​
5. Campos de anexo de política

Os dois campos mais poderosos de uma chave. Cada um vincula a chave a uma política com escopo de workspace que governa seu tráfego — mude a política e cada chave anexada a ela adota a mudança na próxima requisição, sem redeploy.
CampoTipoVincula a chave a
guardrail_idnumberUm guardrail de conteúdo que filtra o texto de requisição e resposta.
firewall_policy_idnumberUma política de firewall que governa as chamadas de ferramenta que a chave emite.
is_firewall_gatewaybooleanMarca a chave como um token com escopo de gateway para as rotas de MCP / evaluate do Firewall (não para inferência).
O sentinela para ambos os anexos é 0 (não anexado). Mas os dois planos resolvem um anexo desabilitado de forma diferente:
  • Um guardrail_id desabilitado é o interruptor de desligar — a chave recebe nenhum guardrail, sem fallback para o padrão do workspace.
  • Um firewall_policy_id desabilitado cai de volta para a política de firewall padrão do workspace.
A ordem completa de resolução vive em Vincular políticas e Escopo & chaves.
is_firewall_gateway: true cunha uma chave com escopo de gateway apenas para as rotas /api/v1/firewall/* — nunca a coloque em uma chave de inferência. Habilitar a flag, e ler o plaintext de uma chave de gateway, ambos exigem Admin+.

​
6. Definindo esses campos

Cada campo acima é configurado no editor de chaves do console (/console/token) — não através de uma chave de relay. Criar ou editar uma chave exige o papel de Developer ou superior; a flag is_firewall_gateway exige Admin+.
O objeto token é a superfície de configuração. O plaintext da chave (sk-orca-…) é o que seu agente apresenta nas chamadas de relay /v1/*. Configure a chave no console; o agente só vê o segredo.
Uma chave de menor agência concreta — definida no editor, relida como o objeto acima — limita um modelo, um intervalo de IP de origem, um teto semanal em USD, uma expiração, e um guardrail mais uma política de firewall. Se o agente que a segura for sequestrado via injeção de prompt, o raio de explosão para exatamente nesses limites.

​
7. Referências relacionadas

Visão geral de chaves com escopo

O modelo de menor agência e o hub para cada campo de chave.

Vincular políticas

Como guardrail_id e firewall_policy_id resolvem para uma política ativa.

Cota, limite & expiração

credit_limit_usd, expired_time e os campos de cota em profundidade.

Checklist de menor agência

Passe cada chave pelo mesmo processo de endurecimento.
Novo no modelo? Leia Escopo, chaves, políticas & workspaces para como o objeto token se encaixa na hierarquia workspace → política → chave.