Skip to main content
A API Pontua usa tokens JWT assinados como API Keys. Toda requisição autenticada envia o token no header Authorization no formato Bearer:
Sem esse header, ou com token inválido/expirado, a resposta será 401 Unauthorized.

Anatomia do token

O token é um JWT (JSON Web Token) com três partes separadas por .:

Payload (claims)

Você pode decodificar o payload (sem validar a assinatura) em jwt.io durante debug. Conteúdo típico:
O token NÃO contém escopo nem permissões granulares hoje. Quem tem o token pode tudo que a API Pontua pública permite naquele tenant. Se você precisa de leitura-only para um sistema downstream, faça um proxy no seu lado que filtre antes de propagar.

Como gerar um token

1

Acesse o dashboard

Entre em oi.pontua.com.br com sua conta administrativa. Navegue até Gestão de Pessoas → Configurações → API.
2

Crie um novo token

Clique em Criar novo token e preencha:
  • Nome identificador — descritivo por integração (ex.: [PROD] erp-totvs, [HML] script-relatorio-mensal). Vai aparecer em logs de auditoria.
  • Validade — entre 7 dias e 5 anos:
3

Copie o token IMEDIATAMENTE

O valor aparece uma única vez. Cole em cofre seguro (1Password, Doppler, AWS Secrets Manager, HashiCorp Vault).

Padrão de wrapper HTTP autenticado

Recomendamos encapsular a lógica de auth em uma função reutilizável:

Armazenamento seguro

Faça

  • Cofre de secrets (1Password, Doppler, AWS SM, HashiCorp Vault)
  • Variável de ambiente em runtime (PONTUA_API_TOKEN)
  • Token diferente por ambiente (PROD/HML/PRE/CI)
  • Token diferente por integração (revogar uma sem afetar outras)
  • Restringir leitura do secret aos serviços que precisam

Não faça

  • ❌ Comitar em repositório git (mesmo privado)
  • ❌ Enviar por e-mail, Slack ou Jira
  • ❌ Usar em código frontend (qualquer JS no browser expõe o token)
  • ❌ Tokens de 5 anos para scripts de desenvolvedor individual
  • ❌ Compartilhar um único token entre times / integrações
  • ❌ Logar o token em arquivos de log ou stdout

Rotação zero-downtime

Recomendamos rotacionar tokens no mínimo a cada 12 meses. Para sistemas críticos, rotação trimestral é mais segura.
1

Gere o novo token (mantém o antigo ativo)

Dashboard ou via API: POST /api-key. Não revogue o antigo ainda.
2

Atualize o secret manager com o novo

Sem deploy ainda. Apenas o secret muda.
3

Faça deploy progressivo

Os pods/instances vão pegar o novo token gradualmente. Monitore logs de erro 401 — se aumentar, faça rollback do secret antes de revogar.
4

Aguarde 24h

Tempo suficiente para todas as caches/sessions/cron jobs pegarem o novo.
5

Revogue o antigo

PATCH /api-key/{id} com status: INATIVO. Daquele momento em diante, chamadas com o token antigo recebem 401.

Erros de autenticação

Todos retornam 401 Unauthorized com envelope { service, method, message }.

Revogação imediata (token vazou)

Se um token vazou (commitado em repo público, mostrado em screen sharing, enviado em email errado), revogue imediatamente — não espere a rotação programada.
  1. Dashboard → Gestão de Pessoas → Configurações → API
  2. Localize o token pelo nome identificador
  3. Clique em Revogar
  4. Token desativado em até 30 segundos. Chamadas subsequentes falham com 401.
  5. Gere novo token e atualize secret antes de re-deployar.
A revogação é irreversível — um token revogado nunca volta a funcionar.

Auditoria e observabilidade

Toda ação realizada via API fica registrada com o nickname do token que a originou. Você pode consultar a trilha em Auditoria no dashboard, filtrando por “Origem: API”. Eventos auditáveis incluem:
  • Criação de colaborador, ajuste de registro de ponto, geração de relatório
  • Mudanças em escalas, turnos, banco de horas
  • Tentativas de revogação ou modificação de tokens
Para suporte, sempre mencione:
  • Nome do token (nickname)
  • Timestamp aproximado (BRT)
  • service, method, message da resposta de erro (se houver)

Veja também