المصادقة

مفتاح لكل حساب، نطاق لكل مفتاح، مؤلف لكل مستخدم.

يحدد المفتاح الحساب (كل بيانات مُعادة تخصه وحده) ويحمل النطاق: قراءة، أو قراءة وكتابة. تتطلب الكتابة مستخدماً مسؤولاً على المفتاح وترويسة Idempotency-Key في POST — تكرار نفس 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.