Autenticação da API

Todos os endpoints REST ficam sob /api/v1. Scripts, jobs de CI e integrações se autenticam com uma chave de API; o painel usa uma sessão por cookie.

Chaves de API

Uma chave de API é a única credencial pensada para programas. Crie uma por ferramenta, assim você revoga uma integração sem afetar as outras:

1. No painel, abra Configurações → Chaves API e clique em Criar chave API.
2. Dê a ela um nome que diga o que a usa, por exemplo "Pipeline de CI".
3. Escolha o nível de acesso e, se quiser, uma data de expiração.
4. Copie a chave imediatamente: ela só é mostrada uma vez e é armazenada como hash. Se a perder, exclua-a e crie outra.

As chaves começam com sh0_. Uma chave nunca pode fazer mais do que a conta que a criou, e uma chave não pode criar outras chaves.

Níveis de acesso

Cada chave tem um de três níveis de acesso, aplicado pelo servidor em cada requisição. Pela API, o nível é o campo scopes: read, deploy ou admin.

Usar uma chave

Envie a chave no cabeçalho Authorization: Bearer de cada requisição:

export SH0_TOKEN="sh0_..."
curl https://panel.example.com/api/v1/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Sessões do painel

O painel faz login com POST /api/v1/auth/login. Em caso de sucesso, o servidor define cookies HttpOnly (sh0_access e sh0_refresh) e devolve um csrf_token no corpo da resposta; nenhum token é devolvido no corpo. Esse fluxo é para navegadores: para scripts, use uma chave de API.

A sessão de acesso dura 24 horas. O painel a renova por POST /api/v1/auth/refresh, que também emite uma nova sessão de renovação de 30 dias; uma sessão sem uso por 30 dias termina.

Alterar a senha encerra todas as outras sessões. As tentativas de login são limitadas a 5 falhas a cada 15 minutos; uma senha correta não conta para o limite.

Login com dois fatores

Quando a conta tem autenticação de dois fatores, o login responde requires_totp com um totp_nonce de curta duração em vez de abrir a sessão. Em seguida, o cliente envia o nonce e o código de 6 dígitos (ou um código de backup) para POST /api/v1/auth/totp/verify. A verificação é limitada a 5 tentativas a cada 5 minutos.

Proteção CSRF

Requisições autenticadas pelo cookie de sessão devem repetir o token CSRF no cabeçalho X-CSRF-Token em toda chamada que altera estado. Requisições autenticadas por uma chave de API no cabeçalho Authorization não precisam dele.

Erros de autenticação

Os erros usam o envelope de erro padrão. Por exemplo, uma chave desconhecida ou revogada:

{"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}