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 | Máximo de 10 chaves ativas por empresa. |
| Expiração | Opcional (90 / 180 / 365 dias ou sem expiraçã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.
Rotação
Rotacionar uma chave = criar uma nova e revogar a antiga. Fluxo sem downtime:
- 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.
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 | A assinatura da empresa está suspensa. |
| 403 | addon_disabled | O addon Public API não está ativo. |
Consulte o formato completo de erros em Convenções → Erros.