Autenticação

Toda requisição carrega uma chave de API do workspace. Não existe fluxo OAuth de client credentials nem endpoint de usuário e senha.

Cabeçalhos

Os dois funcionam. Prefira a forma bearer.

bash

Authorization: Bearer zfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# ou
x-api-key: zfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Nunca chame esta API do navegador. O x-api-key está deliberadamente fora da nossa lista de cabeçalhos permitidos no CORS, então chamada de navegador falha no preflight. Isso não é um obstáculo a contornar: chave que chega ao navegador é chave vazada.

Formato da chave

A chave começa com zfk_ seguido de 32 bytes de CSPRNG em base64url. Do nosso lado guardamos só um hash SHA-256, então não conseguimos mostrar o segredo de novo — ele aparece exatamente uma vez, na criação.

Respostas de falha

Toda credencial recusada devolve o mesmo corpo. Chave ausente, malformada, desconhecida, revogada e expirada são byte a byte idênticas, a menos do id da requisição.

json

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing credentials",
  "request_id": "req_01J..."
}

Isso é deliberado. Dizer qual dos cinco estados se aplica permitiria enumerar chaves válidas e detectar o instante exato em que uma é revogada. O motivo real fica registrado na trilha de auditoria do workspace, onde o proprietário lê.

O que cada status quer dizer

Status	Significado	O que fazer
401	A credencial está ausente, malformada, é desconhecida, foi revogada ou expirou.	Confira a chave; crie outra se ela foi revogada.
403 `FORBIDDEN`	A chave é válida, mas esta capacidade nunca está disponível para chaves.	Não há o que retentar. Rotas de conta pessoal e de administração interna são permanentemente fechadas a chaves.
403 `INSUFFICIENT_SCOPE`	A chave é válida, mas este escopo não foi concedido — ou o papel de quem a criou deixou de tê-lo.	Conceda o escopo, ou peça a um proprietário para criar a chave.
429	Limite de uso.	Respeite o Retry-After.

A regra de autoridade

A permissão efetiva de uma chave é recalculada a cada requisição:

text

efetiva(chave) = escopos(chave)
               ∩ capacidades(papel de quem criou a chave)
               ∩ escopos que chaves podem ter

Então rebaixar um membro estreita na hora toda chave que ele criou, e nenhuma chave carrega capacidade que quem a criou nunca teve.

Rotação

Crie a chave nova, publique, e só então revogue a antiga. A revogação é imediata e permanente — a linha é mantida, nunca apagada, para o registro do que aquela chave fez sobreviver a ela.