Autenticação e chaves de API

A API usa chaves de API de empresa (service accounts, não vinculadas a um usuário). Cada requisição é autenticada com a chave como Bearer token:


curl https://api.kinmu.app/v1/organization \
  -H "Authorization: Bearer kinmu_sk_live_xxxxxxxx"

Natureza das chaves

A empresa é resolvida sempre a partir da chave: você nunca envia um companyId na URL nem no body.

Aspecto	Detalhe
Formato	`kinmu_sk_live_<40+ chars>` (produção) · `kinmu_sk_test_<40+ chars>` (sandbox).
Visibilidade	São exibidas uma única vez na criação. Depois você só verá o prefixo + os primeiros caracteres.
Emissão	Pelo painel my.kinmu.app → Desenvolvedores (apenas `global_admin` / `company_manager`).
Limite	10 chaves ativas por empresa por omissão; configurável por empresa nas definições do addon (`max_active_keys`). O valor em vigor vê-se no painel.
Expiração	Opcional na criação (90 / 180 / 365 dias ou sem expiração). Se a empresa tiver definido `default_expiration_days` e não pedir uma expiração explícita, a chave expira à mesma segundo essa política.

Verifique expires_at na resposta da criação. É a única fonte fiável: mesmo sem pedir expiração, a política default_expiration_days da sua empresa pode ter-lhe posto uma data. Anote-a e agende a rotação.

Scopes

Cada chave carrega scopes explícitos (privilégio mínimo). Sem o scope exigido, o endpoint responde 403 invalid_scope.

Scope	Permite
`org:empleados:read`	Ler funcionários.
`org:empleados:write`	Admitir, atualizar e desligar funcionários.
`org:fichajes:read`	Ler pontos e work-summaries.
`org:fichajes:write`	Registrar pontos.
`org:ausencias:read`	Ler ausências.
`org:ausencias:write`	Criar, aprovar e recusar ausências.
`org:saldos:read`	Ler saldos de férias.
`org:estructura:read`	Ler locations e units.
`org:informes:read`	Solicitar e baixar relatórios.
`webhooks:manage`	Gerenciar webhooks de saída.

GET /v1/organization não exige um scope específico: serve para introspecção e para validar a chave. Os relatórios exigem também o scope de leitura do seu domínio: por exemplo, absences_export exige org:ausencias:read.

Conceda a cada integração apenas os scopes de que ela precisa.

Sandbox

As chaves kinmu_sk_test_ operam sempre sobre uma empresa sandbox com dados sintéticos, isolada dos seus dados reais. Veja o guia de Sandbox.

Desativar o addon Public API revoga TODAS as chaves de API da empresa (motivo addon_disabled) e elimina a empresa sandbox com os seus dados. Voltar a ativá-lo não as ressuscita: é preciso emitir chaves novas. Veja o ciclo de vida.

Rotação

Existe rotação atómica: um clique no painel do Kinmu (Programadores → API keys) emite a chave substituta mantendo scopes, nome, ambiente e política de expiração e revoga a anterior na mesma transação. O novo segredo é mostrado uma única vez, tal como numa criação. O /v1 não expõe gestão de chaves: criar, rotacionar e revogar faz-se sempre pelo painel.

Uma chave já revogada não pode ser rotacionada: para a substituir, crie uma nova.

Se preferir sobrepor as duas chaves para fazer o deploy sem downtime, faça-o à mão:

Crie a nova chave com os mesmos scopes.
Faça o deploy da sua integração com a nova chave.
Verifique que funciona (por exemplo, um GET /v1/organization).
Revogue a chave antiga.

Revogação

A revogação é imediata pelo painel: a chave deixa de funcionar no request seguinte (401 unauthenticated). Revogue na hora qualquer chave que você suspeite estar comprometida e verifique o last_used_ip dela.

Revogar chaves e webhooks (DELETE) funciona mesmo com a subscrição inativa: é um controlo de segurança, não consumo do serviço. Nunca fica sem forma de cortar uma credencial comprometida.

Boas práticas

Nunca publique uma chave em código cliente, apps móveis, repositórios ou logs. São credenciais de servidor.
Guarde-as em um gerenciador de segredos ou em variáveis de ambiente.
Use uma chave por integração para poder revogar de forma granular.
Aplique privilégio mínimo: apenas os scopes indispensáveis.
Configure expiração e rotacione periodicamente.
Em logs, nunca registre o header Authorization.

Erros de autenticação

HTTP	`code`	Causa
401	`unauthenticated`	Chave ausente, inválida, revogada ou expirada.
403	`invalid_scope`	A chave não tem o scope exigido (`errors.required_scope`).
403	`subscription_inactive`	Empresa suspensa ou arquivada, sem subscrição, subscrição suspensa, período experimental esgotado, ou subscrição cancelada e já terminada ou expirada. É sempre 403, nunca 402.
403	`addon_disabled`	O addon Public API não está ativo.

Consulte o formato completo de erros em Convenções → Erros.