Аутентификация

Ключ на аккаунт, scope на ключ, авторство на пользователя.

Ключ идентифицирует АККАУНТ (все возвращаемые данные — только его) и несёт scope: чтение или чтение и запись. Запись требует ответственного пользователя на ключе и заголовка 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.