Autenticação e escopos

O header#

Toda chamada leva a chave no header Authorization, esquema Bearer. Não há chave por query string nem por cookie — chave em URL vaza em log, histórico e Referer.

Authorization: Bearer gsk_a1b2c3d4KZ8mQvR7tYw2NpX5LhJ0eSg6UdF9BcA3iOk

A sessão do painel não vale aqui, de propósito: ela dura 7 dias, carrega a identidade da pessoa e morre na troca de senha. Uma credencial de máquina precisa viver o tempo da integração, ser revogável sozinha e fazer só um pedaço do que a pessoa faz.

A chave#

Escopos#

Cada endpoint exige um escopo, e a chave só carrega os que você marcou. Uma chave de leitura vazada não dispara ronda nem gasta cota — expõe relatórios, o que já é grave, mas não vira gerador de tráfego e de fatura.

Regra prática: o passo de CI que só decide falhar o build pelo risco da última ronda precisa de scans:read e nada mais. Dê scans:write só à integração que dispara.

A declaração de autorização#

Ao criar uma chave com scans:write, você marca a checkbox “só escaneio apps meus ou com autorização expressa do responsável”. A Guarita grava a declaração com data, versão dos Termos, IP e user-agent — uma vez, na chave, como nas integrações da Vercel e do Lovable.

• Vale pra toda ronda disparada com a chave. Por isso POST /scans não pede authorized no corpo.
• Chave só de leitura não declara nada: ela não escaneia.
• Cada ronda continua registrando a autorização (data, versão dos Termos, IP e user-agent) — a declaração da chave é a origem dela.
• O modo agressivo pede uma confirmação a mais, por ronda: authorized_intrusive: true — veja as opções da ronda.

401 vs 403#

{
  "error": "unauthorized",
  "message": "Chave de API ausente ou inválida. Envie `Authorization: Bearer gsk_...` — crie a sua em Configurações > Desenvolvedores."
}

{
  "error": "insufficient_scope",
  "message": "Esta chave não tem a permissão \"scans:write\".",
  "required": "scans:write"
}

Plano#

A API faz parte dos planos Pro e Business. O plano é reavaliado em toda requisição, não só na criação da chave:

• Conta cai pra um plano sem API → toda chamada responde 401 no mesmo instante. As chaves não são revogadas nem apagadas.
• Conta volta pra um plano com API → as mesmas chaves voltam a funcionar. Nada pra reemitir.
• Revogar funciona em qualquer plano. Tirar acesso nunca depende de pagar.

Um 401 repentino numa integração estável há meses costuma ser cobrança, não credencial. Confira o plano antes de rotacionar.

Rotacionar e revogar#

Revogar vale na hora: a chave é resolvida por hash a cada request, com o filtro de revogação dentro da própria consulta. Não há cache nem token auto-contido que sobreviva.

1. Crie a chave nova com os mesmos escopos.
2. Troque a variável de ambiente em todos os lugares onde a antiga roda.
3. Confirme com GET /me usando a nova.
4. Revogue a antiga. As duas convivem enquanto durar a troca.

A lista de chaves mostra a data do último uso — é por ela que você acha a chave esquecida antes de revogar.

A chave é uma senha#

• Não vai pro repositório. Nem em exemplo, nem em commit que você pretende reescrever. Git guarda tudo.
• Não vai pro front-end. Segredo em código que roda no navegador é público. Chame a API do servidor, do CI ou de uma função serverless. O CORS da Guarita libera só a origem do painel, então do navegador nem funcionaria.
• Não vai pro suporte, print ou log. Apareceu em um desses? Considere vazada e rotacione. O key_id de GET /me basta pra identificar a chave.