प्रमाणीकरण

प्रति खाता कुंजी, प्रति कुंजी दायरा, प्रति उपयोगकर्ता लेखक।

कुंजी खाते की पहचान करती है (लौटाया हर डेटा केवल उसी का) और दायरा रखती है: पढ़ना, या पढ़ना-लिखना। लिखने के लिए कुंजी पर ज़िम्मेदार उपयोगकर्ता और POST में Idempotency-Key हेडर चाहिए — एक ही idempotency कुंजी से वही POST दोहराने पर दो बार नहीं बनता। ब्राउज़र से आने वालों का रास्ता कॉर्पोरेट लॉगिन (SSO/SAML) या जुड़ा ऐप (OAuth) है, 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.