Autenticação e chaves

Toda rota da API pública (exceto healthz) exige o header x-api-key:

curl -s https://api.v3.zabit.com.br/kyc/v1/dossiers -H "x-api-key: zbt_SUA_CHAVE"

Não existe Authorization: Bearer nesta superfície, e a chave nunca vai na URL.

A chave

• Você gera a chave na tela de Chaves de API do workspace, no app da Zabit (prod). Não há cadastro via suporte.
• O valor tem o prefixo zbt_ e é mostrado uma única vez, na criação. O servidor guarda só um hash: ninguém — nem o suporte — consegue reler o valor. Perdeu? Gere outra.
• A chave pertence a um workspace e só enxerga os dados dele.
• A chave vale só no ambiente em que foi criada. Cada ambiente é isolado dos demais: uma chave gerada em um ambiente não funciona em outro. Gere a chave no app do mesmo ambiente da API que você vai chamar.
• Ela nasce restrita às rotas do plano de API do workspace naquele momento.
• Trate a chave como uma conta bancária aberta: abrir dossiê dispara consulta paga. Guarde em cofre de segredos, nunca em código, repositório ou aplicativo de celular/navegador.

Rotação

Não há "editar o valor". Para rodar a chave sem interrupção:

1. Gere uma chave nova na tela.
2. Troque o valor no seu cofre e faça o deploy dos seus serviços.
3. Confirme que o tráfego passou a usar a nova (liste dossiês com ela).
4. Revogue a antiga.

Revogação — e o atraso de até 300 s

Revogar uma chave não é instantâneo: ela pode continuar sendo aceita por até 300 segundos (5 minutos) depois da revogação. Faça a rotação com a antiga ainda válida e revogue só depois de confirmar a nova; se a chave vazou, revogue na hora e considere esses 5 minutos de exposição ao planejar a resposta.

Dentro dessa janela, uma leitura pode ainda passar; já a abertura de dossiê confere o estado da chave no momento da chamada e é recusada com 403 forbidden.

Cota diária por chave

Cada chave tem um teto diário de aberturas de dossiê, definido por quem administra o workspace.

• Só POST /kyc/v1/dossiers consome cota (1 por abertura). Listar, consultar e checar KYC vigente não consomem.
• O contador zera à meia-noite UTC.
• Chave sem teto configurado não abre dossiê: a API recusa com 403 quota_not_configured em vez de tratar a ausência como "ilimitado".
• A unidade é consumida antes de enfileirar e não é estornada se a abertura falhar depois.
• Há também um freio do workspace (diário e mensal) que soma tela, importação e API: 429 kyc_creation_limit_reached.

Erros de autenticação e autorização

Status	error.code	Quando	O que fazer
401	unauthorized	Header x-api-key ausente, chave desconhecida ou token inválido.	Confira o header e se o valor está completo (zbt_…). Não adianta repetir.
403	forbidden	Chave revogada ou desabilitada; escopo da chave não cobre a operação; workspace inativo; ou credencial que não é chave de API.	Gere/ative outra chave com o escopo certo.
403	quota_not_configured	A chave não tem teto diário.	Peça ao administrador do workspace para definir o teto.
403	route_not_in_plan	O plano de API do workspace não inclui esta rota (conferido a cada chamada).	Fale com o administrador do workspace. Nenhuma cota é gasta.
429	quota_exceeded	Teto diário da chave esgotado.	Aguarde o próximo dia (UTC) ou peça aumento do teto.
429	kyc_creation_limit_reached	Freio de criação do workspace (diário ou mensal).	Aguarde; details.periodo e details.volta_a_valer_em, quando presentes, dizem qual e até quando.

Mais sobre o formato e o tratamento: Erros.

Um 429 só vale para quem voltaria a funcionar

A API ordena as checagens para que um 429 só apareça numa chave que, em outro momento, funcionaria. Chave revogada ou sem escopo recebe 403, nunca 429. Se você recebe 429, esperar resolve; se recebe 403, esperar não resolve.