Authentication

One key per account, a scope per key, authorship per user.

The key identifies the ACCOUNT (every returned record is only its own) and carries the scope: read, or read and write. Writing requires a responsible user on the key and an Idempotency-Key header on POST — repeating the same POST with the same idempotency key does not create twice. For people entering through the browser, the way is corporate login (SSO/SAML) or a connected app (OAuth), not the API key.

How to send the key

Send the key in one of the two headers below on every call. If both come, Authorization wins.

Header	Value	Description
`Authorization`	`Bearer <chave>`	Recommended.
`X-API-Key`	`<chave>`	Alternative for tools that cannot build Bearer.

Scopes

Key scope	Description
`READ`	Reads every resource of the account. POST, PUT, PATCH and DELETE answer 403.
`READ_WRITE`	Reads and writes. Requires a responsible user on the key: every write is logged under that name.

Key identity

A key is issued in the name of an active person of the account and is worth what that person's screen shows. When the identity becomes irregular (person deactivated, key without owner), the account decides whether the API only warns — in the X-Tenka-Aviso and Warning headers — or refuses with 403.

Authentication errors

HTTP	Message (erro field)	When it happens
401	`chave de API ausente ou inválida`	No key header, revoked key or typo.
401	`chave sem empresa vinculada`	The key exists but is not linked to an account. Create another one in Settings › API.
403	`conta de demonstração: a API pública está desligada na vitrine`	The call reached the demo account, where the public API is turned off.
403	`identidade da chave de API irregular`	The account refuses keys with irregular identity (deactivated person or ownerless key). The body brings motivo and comoResolver.
429	`limite de requisições excedido (120/min)`	The key went over its per-minute limit. Wait for Retry-After.
403	`esta chave é somente leitura — gere uma chave com escopo de escrita`	Write with a read-only key.
409	`a chave não tem usuário responsável; recrie a chave em Configurações → API para que os registros criados tenham autoria`	The write key has no responsible user: without authorship nothing is saved.