Autenticação
Dois métodos de autenticação para diferentes contextos de uso.
Visão Geral
A plataforma Avizuaí oferece dois mecanismos de autenticação independentes:
| Método | Uso | Escopo |
|---|---|---|
| API Key + Secret | Integradores externos | API v2 (/api/external/**) |
| JWT Bearer Token | Painel administrativo | API Admin (/api/admin/**) |
API Key + Secret (API v2)
Para integrações externas, utilize os headers X-Api-Key e X-Api-Secret em todas as requisições.
Obtendo as Credenciais
As credenciais são geradas automaticamente ao cadastrar uma aplicação no painel admin. O API Secret é exibido apenas uma vez — armazene-o em local seguro.
Exemplo de Requisição
curl http://localhost:8082/api/external/financeiro/saldo \
-H "X-Api-Key: ak_1234567890abcdef" \
-H "X-Api-Secret: sk_abcdef1234567890"
Erros de Autenticação
Se as credenciais forem inválidas ou ausentes, a API retorna 401 Unauthorized:
{
"status": 401,
"error": "Unauthorized",
"message": "Credenciais inválidas",
"timestamp": "2024-04-11T10:30:00"
}
JWT Bearer Token (API Admin)
A API Admin utiliza autenticação via JWT (JSON Web Token). Primeiro, obtenha um token através do endpoint de login.
Login
POST
/api/admin/auth/login
Request body:
{
"email": "admin@example.com",
"senha": "sua-senha"
}
Resposta (200):
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"tipo": "Bearer",
"usuario": {
"id": 1,
"nome": "João Silva",
"email": "admin@example.com",
"nivel": "ADMINISTRADOR"
}
}
Usando o Token
Inclua o token no header Authorization de todas as requisições à API Admin:
curl http://localhost:8082/api/admin/aplicacoes \
-H "Authorization: Bearer eyJhbGciOi..."
Erros de Login
| Código | Situação | Resposta |
|---|---|---|
401 | Email ou senha incorretos | {"erro": "Credenciais inválidas"} |
403 | Usuário desativado | {"erro": "Usuário inativo"} |
Segurança
Importante: Nunca exponha suas credenciais em código client-side (JavaScript no navegador, apps mobile sem ofuscação). Utilize sempre chamadas server-to-server.
- API Keys são únicas por aplicação e podem ser regeneradas no painel admin
- Tokens JWT possuem prazo de expiração configurável
- Em produção, todas as requisições devem usar HTTPS
- O API Secret é armazenado como hash — não pode ser recuperado, apenas regenerado