Guia de Autenticação
A API My ID Virtual utiliza múltiplas camadas de segurança para proteger os recursos e garantir que apenas usuários autorizados tenham acesso aos dados.
Tipos de Autenticação
1. JWT (JSON Web Token)
O método principal de autenticação utiliza tokens JWT que devem ser incluídos no header Authorization:
Authorization: Bearer <seu_jwt_token>
2. OTP (One-Time Password)
Para operações sensíveis, é possível configurar autenticação de dois fatores (2FA) usando OTP.
3. Guards Customizados
- CustomerAuthGuard: Para operações específicas de clientes
- AccountAppAuthGuard: Para operações de aplicações de conta
Fluxo de Autenticação
Login
Envie credenciais para /auth/signin ou /auth/signin/passid
Receba o Token
A API retorna um JWT token válido
Use o Token
Inclua o token no header Authorization de todas as requisições
Refresh quando Necessário
Use /auth/refresh para renovar tokens expirados
Exemplo de Login
curl --location --request POST 'http://localhost:3333/auth/signin' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "[email protected]",
"password": "senha123"
}'
Usando o Token
Após obter o token, inclua-o em todas as requisições autenticadas:
curl --location --request GET 'http://localhost:3333/auth/me' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
Níveis de Autorização
Papéis de Usuário
| Papel | Descrição | Permissões |
|---|
| ADMIN | Administrador do sistema | Acesso total a todos os recursos |
| MASTER | Administrador limitado | Gerenciar revendedores e seus clientes |
| RESALE | Revendedor | Gerenciar apenas seus próprios clientes |
| CUSTOMER | Cliente final | Acesso apenas aos próprios recursos |
Verificação de Permissões
Muitos endpoints verificam não apenas se o usuário está autenticado, mas também se possui o papel necessário:
@Roles('ADMIN', 'MASTER')
@UseGuards(AuthGuard('jwt'), RolesGuard)
Configuração OTP
Para habilitar autenticação de dois fatores:
- Gerar OTP:
POST /auth/otp/generate
- Adicionar OTP:
POST /auth/otp/add
- Verificar OTP:
POST /auth/otp/verify
curl --location --request POST 'http://localhost:3333/auth/otp/generate' \
--header 'Authorization: Bearer <token>'
Refresh Token
Quando um token expira, use o endpoint de refresh:
curl --location --request POST 'http://localhost:3333/auth/refresh' \
--header 'Content-Type: application/json' \
--data-raw '{
"refresh_token": "seu_refresh_token"
}'
Códigos de Erro Comuns
| Código | Descrição | Solução |
|---|
401 | Token inválido ou expirado | Faça login novamente ou use refresh |
403 | Permissões insuficientes | Verifique se seu usuário tem o papel necessário |
422 | Dados de login inválidos | Verifique email e senha |
Nunca compartilhe seus tokens JWT. Eles devem ser tratados como credenciais sensíveis.
Configure um sistema de refresh automático em sua aplicação para evitar interrupções no serviço.
