Ir para o conteúdo

Roteiro: Emitir chave de API (PAT) para integração via Bearer

Perfil necessário: admin Menus usados: Administração Risco: alto (PAT é permanente até revogação: concede o papel do usuário dono na API; segredo exibido uma única vez) Rollback: revogar a chave na tabela Chaves de API (PAT); integração deixa de autenticar imediatamente

Pré-requisitos

  • [ ] Login como usuário com perfil admin (a rota /users é exclusiva de admin)
  • [ ] Destinatário da chave já cadastrado em Usuários (a chave pertence a um usuário do painel)
  • [ ] Cofre de segredos (password manager, vault, secret manager) acessível antes de criar a chave

Passo a passo

1. Abrir a seção de chaves API

Caminho: Avatar do usuário → Gerenciar Usuários (ou URL /users); role até o card Chaves de API (PAT)

Card Chaves de API (PAT) com o botão Nova chave API destacado

Clique: [Nova chave API]

Resultado esperado: dialog Nova chave API abre.

2. Preencher o dialog Nova chave API

Dialog Nova chave API com usuário, nome e expiração

Preencha:

Campo Obrig. Formato/exemplo Efeito
Usuário * Sim select com todos os usuários do painel Dono da chave: a API aplica o papel (admin/viewer) dele
Nome da chave * Sim monitoring-bot Identificação na lista e nos logs de auditoria
Definir expiração Não toggle desativado por default Sem expiração = chave permanente (comportamento PAT)
Data/hora de expiração Só se o toggle estiver ativo DatePicker com hora (24h), formato dd/mm/yy Após esta data a chave volta Expirada e é rejeitada

Clique: [Criar chave]

Resultado esperado: dialog Chave API criada abre.

3. Copiar o segredo NA HORA

Dialog Chave API criada com aviso de exibição única e botão Copiar

Clique: [Copiar]

Resultado esperado: toast "Token copiado para a área de transferência".

⚠️ O token completo (pat_...) é exibido UMA ÚNICA VEZ. Ao fechar o dialog ele não pode mais ser recuperado — só o prefixo fica na tabela. Cole o valor no cofre de segredos antes de fechar. Se perder o segredo, revogue e emita outra chave.

4. Usar o PAT na API

O token substitui o JWT no header Authorization de qualquer endpoint do admin:

curl -H "Authorization: Bearer pat_XXXXXXXX" \
     http://127.0.0.1:8080/api/auth/me

Resultado esperado: JSON do usuário dono da chave (prova de autenticação OK). Endpoints de escrita falham com 403 se o usuário dono for viewer.

5. Revogar uma chave

Na tabela Chaves de API (PAT), na linha da chave, Clique: [Revogar chave API] (ícone de banimento em Ações)

Confirmação de revogação da chave API

Confirme com Revogar no modal.

Resultado esperado: toast "Chave API revogada com sucesso"; Status muda para Revogada e o botão fica desabilitado. O botão também fica desabilitado para chaves Inativa ou Expirada (nada a revogar).

Validação

  • [ ] Visual: chave nova listada com Status Ativa, prefixo visível e usuário dono correto
  • [ ] Funcional: chamada com Bearer <pat> retorna 200 em /api/auth/me
  • [ ] Funcional: após revogar, a mesma chamada retorna 401
  • [ ] Auditoria: eventos create_api_token / revoke_api_token registrados no log de auditoria do admin

Erros comuns

Sintoma Causa provável Correção
Toast "Usuário e nome da chave são obrigatórios" campos * vazios preencher Usuário e Nome da chave
Toast "Selecione a data de expiração" toggle ativo sem data preencher o DatePicker ou desligar a expiração
API responde 401 após criar segredo não copiado / token errado o segredo não é recuperável: revogar e emitir nova chave
API responde 403 em escrita com PAT válido usuário dono é viewer emitir a chave para um usuário admin
Botão Revogar desabilitado chave já revogada/inativa/expirada nada a fazer — status já está final

Tabela de referência rápida

Tarefa Onde
Criar PAT Usuários → Chaves de API (PAT) → Nova chave API
Ver uso da chave Coluna Último uso da tabela
Revogar Ícone de banimento na linha → Revogar
Testar curl -H "Authorization: Bearer pat_..." /api/auth/me