Início rápido

Siga o Guia de Autenticação para fazer login, depois abra a página de Chaves de Gerenciamento e crie uma chave de gerenciamento. Armazene-a separadamente das chaves de aplicação padrão. Envie-a como um token bearer somente para endpoints de Platform Management.

Uma Chave de API padrão não pode chamar endpoints de gerenciamento de chaves ou guardrails. Uma chave de gerenciamento válida ainda pode receber 403 Forbidden quando seu proprietário não possuir mais a função de conta necessária.

Use GET /api/v1/keys para inspecionar as chaves visíveis à conta da chave de gerenciamento:

Use os identificadores públicos retornados para requisições posteriores de recuperação, atualização, revogação ou atribuição de guardrail. Nunca infira acesso a partir do nome de uma chave ou de um token mascarado.

Crie uma chave de aplicação com POST /api/v1/keys. O segredo completo é retornado apenas na resposta de criação, portanto persista-o no seu gerenciador de segredos antes de descartar essa resposta. A rotação deve criar uma substituição, implantá-la na aplicação, verificar o tráfego e revogar a chave antiga.

credit_limit_windows aceita qualquer combinação de limites de gastos contínuos 1h, 1d e 7d. Se qualquer janela configurada for esgotada, as chamadas com essa chave retornam 429 Too Many Requests até que o uso saia da janela. Envie um objeto vazio ao atualizar uma chave para remover todos os limites contínuos.

Quando uma solicitação de criação omite todos os campos de limite de gastos e guardrail_id, a nova chave usa os padrões de governança do espaço de trabalho. Limites explícitos, janelas móveis ou um guardrail substituem essa escolha padrão. Envie credit_limit_cents: null para criar um limite nativo ilimitado. Um valor informado sem intervalo de redefinição continua sendo um limite vitalício. As atualizações nunca reaplicam os padrões do espaço de trabalho, e alterar esses padrões não modifica as chaves existentes.

Criação e atualização aceitam tags, um array de strings key:value completas. As respostas de listagem, consulta, criação e atualização retornam o array completo. PATCH substitui o array; omitir tags o preserva. A chave deve ter 1–32 caracteres e o valor 1–64, com exatamente um sinal de dois-pontos e sem espaços em branco. São permitidas até 20 tags distintas, incluindo as predefinidas. Formatos inválidos ou valores predefinidos conflitantes retornam 422 com erros de validação; um valor que não seja array ou um elemento que não seja string retorna 400.

É obrigatória exatamente uma tag de finalidade: usage:developer ou usage:service. A criação pela Management API adiciona usage:service quando nenhuma finalidade é informada, inclusive com tags: []. A criação no Dashboard e as atualizações sem finalidade usam usage:developer. As chaves existentes são migradas como Developer. O ambiente é opcional e aceita no máximo um entre env:production, env:staging ou env:dev (env:prod não é aceito).

A criação/edição no Dashboard oferece seleção rápida de finalidade e ambiente, tags personalizadas e sugestões apenas das chaves padrão não descartadas do workspace atual. As listas mostram os valores e a tag completa ao passar o cursor. As tags não alteram propriedade, visibilidade ou permissões da chave. Elas podem associar uma chave a um orçamento compartilhado por tag.

Administradores do workspace definem as tags obrigatórias de um membro em Equipe, pelo formulário de orçamento do membro. São tags personalizadas que diferenciam maiúsculas de minúsculas, como team:growth. Os namespaces usage: e env: são reservados. Um membro pode ter no máximo 19 tags obrigatórias, e cada chave continua limitada a 20 tags no total.

Toda nova chave padrão inclui automaticamente as tags obrigatórias de seu proprietário naquele workspace. A criação combina as tags enviadas com as obrigatórias antes da validação. Por exemplo, se o membro exige team:growth, uma solicitação de criação pela Management API com tags: ["project:chatbot"] retorna project:chatbot, team:growth e a tag padrão usage:service.

Uma solicitação PATCH que envia tags deve manter todas as tags obrigatórias. Remover uma delas retorna 422 com um erro de validação que identifica as tags ausentes, mesmo quando o solicitante é administrador. Omitir tags preserva as tags da chave. Os membros ainda podem adicionar ou remover tags comuns.

Para remover uma tag obrigatória, um administrador altera a configuração do membro em Equipe. Salvar a configuração adiciona as novas tags obrigatórias a todas as chaves padrão existentes desse membro e remove as tags que deixaram de ser obrigatórias. As demais tags permanecem inalteradas. Isso inclui chaves desativadas e expiradas, mas exclui as excluídas. Se alguma chave não aceitar o conjunto final de tags, todo o salvamento falha e o formulário identifica a chave a corrigir.

Os orçamentos por tag usam as tags atuais de cada chave. Alterar as tags obrigatórias também altera a atribuição dos gastos existentes aos orçamentos no período atual. Adicionar uma tag obrigatória pode esgotar seu orçamento imediatamente. Os membros existentes começam sem tags obrigatórias, e suas chaves permanecem inalteradas até que um administrador salve uma configuração.

Guardrails são políticas de conta reutilizáveis para controles de modelo, provedor e gastos. Gerencie as políticas em /api/v1/guardrails, depois use /api/v1/guardrail_assignments para vinculá-las ou removê-las. Trate um assignment rejeitado como uma falha de política ou propriedade em vez de continuar silenciosamente sem o guardrail.

Crie uma proteção positiva no modo block e atribua seu guardrail_id e uma tag sensível a maiúsculas como dept:ml. Escolha exatamente um destino, api_token_id, account_user_id ou tag. Orçamentos por etiqueta exigem um administrador. Os desativados não aplicam limites. Solicitações de gerenciamento não consomem orçamento.

Os orçamentos agregam as etiquetas atuais das chaves padrão, incluindo gastos de chaves excluídas, desativadas e expiradas. Adicionar ou remover uma etiqueta move o gasto da chave no período atual. Criar ou recriar um orçamento nunca zera os gastos. A contagem exclui chaves excluídas. Todos os orçamentos correspondentes devem permitir a solicitação; a rejeição retorna 403 e o nome da etiqueta.

Um credit_limit_reset_interval nulo indica um limite vitalício. Os outros períodos usam UTC. O limite de alerta padrão é 80 e aceita de 1 a 100. Atualizações diretas afetam todas as atribuições; o painel copia a política antes de editar um orçamento por etiqueta.

A admissão verifica as reservas. A liquidação pode excedê-las, mostrar uso acima de 100% e bloquear solicitações pagas posteriores. Os registros usam seu horário de criação; tarefas pendentes e lotes usam o próprio. Uma tarefa aceita em um período pode ser liquidada em outro posterior.