Guias

Autenticação

Como as chaves de API funcionam, como escopá-las e como rotacionar uma sem interromper o serviço.

Toda requisição carrega um bearer token no cabeçalho Authorization. Não existe nenhum outro esquema de autenticação.

bash
curl https://api.trystac.com/v1/chat/completions \
  -H "Authorization: Bearer $STAC_API_KEY"

Uma chave ausente, malformada, inválida ou expirada retorna 401. Não existe caso 403 — uma chave é criada no escopo de um único stack, então não há um estado de "chave válida, stack errado" para relatar.

Escopo da chave

Uma chave pertence a exatamente um stack. Ela não pode ler a base de conhecimento de outro stack, não pode alterar o comportamento e não pode acessar a API do dashboard. O raio de alcance de uma chave vazada é um único stack.

Expiração

Chaves podem expirar. Escolha um prazo na criação:

expires_atstring | nullOpcionalPadrão: null

Carimbo de data/hora em ISO 8601, ou null para uma chave que nunca expira. Requisições com uma chave expirada retornam 401.

today7d30d90dcustomnone
namestringObrigatório

Rótulo exibido no dashboard. Use o nome do consumidor — checkout-service, não chave 3 — para que a revogação posterior seja inequívoca.

Chaves de curta duração são a opção padrão certa para CI e para qualquer coisa rodando em uma máquina que você não controla.

Rotacionando sem interrupção

  1. Crie a substituta

    Um stack aceita múltiplas chaves ativas, então a nova já funciona antes da antiga ser removida.

  2. Implante-a

    Atualize o segredo e faça o rollout do seu serviço. Ambas as chaves são válidas durante a implantação.

  3. Confirme que a chave antiga está inativa

    A página de Usage (Uso) mostra o último uso por chave. Aguarde até que a chave antiga esteja sem atividade por um ciclo completo de deploy.

  4. Revogue

    A revogação é imediata — requições em voo são finalizadas, as novas recebem 401.

Tratando falhas

StatusCausa
401Nenhum cabeçalho Authorization, uma chave não reconhecida ou uma chave além de seu expires_at

O corpo da resposta é { "detail": "..." } — veja Erros para a estrutura completa de erros. Um 401 nunca é retryável: trate-o como um problema de configuração, não como um erro transitório — retries com a mesma chave falharão da mesma forma.