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)

Clique: [Nova chave API]
Resultado esperado: dialog Nova chave API abre.
2. Preencher o dialog Nova chave API¶

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¶

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)

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_tokenregistrados 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 |