Autenticação

Chave por conta, escopo por chave, autoria por usuário.

A chave identifica a CONTA (todo dado devolvido é só dela) e carrega o escopo: leitura, ou leitura e escrita. Escrita exige usuário responsável na chave e cabeçalho Idempotency-Key no POST — repetir o mesmo POST com a mesma chave de idempotência não cria duas vezes. Para pessoas entrando pelo navegador, o caminho é o login corporativo (SSO/SAML) ou um aplicativo conectado (OAuth), não a chave de API.

Como mandar a chave

A chave vai em um dos dois cabeçalhos abaixo, em toda chamada. Se os dois vierem, vale o Authorization.

Cabeçalho	Valor	Descrição
`Authorization`	`Bearer <chave>`	Forma recomendada.
`X-API-Key`	`<chave>`	Alternativa para ferramentas que não montam Bearer.

Escopos

Escopo da chave	Descrição
`READ`	Lê todos os recursos da conta. POST, PUT, PATCH e DELETE respondem 403.
`READ_WRITE`	Lê e grava. Exige usuário responsável na chave: toda escrita fica na trilha com o nome dele.

Identidade da chave

A chave é emitida no nome de uma pessoa ativa da conta e vale o que a tela dela mostra. Quando a identidade fica irregular (pessoa desligada, chave sem dono), a conta decide se a API só avisa — nos cabeçalhos X-Tenka-Aviso e Warning — ou recusa com 403.

Erros de autenticação

HTTP	Mensagem (campo erro)	Quando acontece
401	`chave de API ausente ou inválida`	Sem cabeçalho de chave, chave revogada ou digitada errada.
401	`chave sem empresa vinculada`	A chave existe mas não está ligada a uma conta. Gere outra em Configurações › API.
403	`conta de demonstração: a API pública está desligada na vitrine`	A chamada veio para a conta de demonstração: lá a API pública fica desligada.
403	`identidade da chave de API irregular`	A conta recusa chaves com identidade irregular (pessoa desligada ou chave sem dono). O corpo traz motivo e comoResolver.
429	`limite de requisições excedido (120/min)`	Passou do limite por minuto da chave. Espere o Retry-After.
403	`esta chave é somente leitura — gere uma chave com escopo de escrita`	Escrita com chave de escopo somente leitura.
409	`a chave não tem usuário responsável; recrie a chave em Configurações → API para que os registros criados tenham autoria`	A chave de escrita não tem usuário responsável: sem autoria, nada é gravado.