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: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6...
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 .: 
{header}.{payload}.{signature}

​
Payload (claims)

Você pode decodificar o payload (sem validar a assinatura) em jwt.io durante debug. Conteúdo típico: 
{
  "tenantId": 416141,
  "nickname": "API.1",
  "iat": 1714060800,
  "exp": 1761350400
}
ClaimDescrição
tenantIdID interno da unidade de negócio. Resolve qual banco será consultado em todas as chamadas
nicknameIdentificador da API Key (ex.: API.1) — aparece em logs de auditoria
iatIssued at (timestamp Unix da geração)
expExpira em (timestamp Unix do fim da validade)
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:
ValidadeCaso de uso
7 diasScripts one-shot, testes manuais, POCs
30 diasHomologações, integrações experimentais
45 / 90 / 180 diasIntegrações em evolução, ciclos de revisão
1 anoIntegrações estáveis com rotação anual programada
5 anosSistemas críticos onde rotação manual é inviável (use com cautela)
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: 
class PontuaClient {
  constructor({ token, baseUrl = 'https://api.pontua.com.br' }) {
    if (!token) throw new Error('PONTUA_API_TOKEN obrigatório')
    this.token = token
    this.baseUrl = baseUrl
  }

  async fetch(path, init = {}) {
    const response = await fetch(`${this.baseUrl}${path}`, {
      ...init,
      headers: {
        Authorization: `Bearer ${this.token}`,
        Accept: 'application/json',
        ...init.headers,
      },
    })

    if (response.status === 401) {
      const erro = await response.json()
      throw new TokenInvalidoError(erro.message)
    }

    if (!response.ok) {
      const erro = await response.json()
      throw new PontuaApiError(response.status, erro)
    }

    return response.json()
  }
}

const pontua = new PontuaClient({ token: process.env.PONTUA_API_TOKEN })
const { resultados } = await pontua.fetch('/colaborador?pagina=0&limite=10')

​
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 }.
MensagemCausa típicaAção
Token inválidoMalformado, assinatura corrompida, ou de ambiente erradoCheque que Bearer tem espaço, e que o token é do ambiente correto
Token expiradoAtingiu exp (claim)Gere novo token, atualize secret
Acesso não autorizadoHeader Authorization ausente ou token revogadoConfirme que está enviando o header (cuidado com proxies que filtram)
{
  "service": "AuthCoreGuard",
  "method": "canActivate",
  "message": "Token expirado"
}

​
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