Tema
Autenticação
Login funciona offline em modo local: usuários, roles, permissões e sessões ficam no banco local, então a clínica autentica sem internet. O contexto da empresa é sempre resolvido antes de emitir token. Detalhes de engenharia em docs/auth.md.
| Método | Rota | Auth | Descrição |
|---|---|---|---|
| POST | /api/auth/login | pública | autentica e devolve access + refresh token |
| POST | /api/auth/refresh | pública | troca refresh token por novo access token |
| POST | /api/auth/logout | pública | revoga a sessão de um refresh token |
| GET | /api/auth/me | Bearer | usuário autenticado atual (roles + permissões) |
| POST | /api/auth/change-password | Bearer | troca a senha (revoga as sessões) |
| POST | /api/auth/forgot-password | pública | solicita reset (apenas online) |
| POST | /api/auth/validate-session | pública | valida um access token offline |
Login
bash
curl -X POST $BASE/api/auth/login -H 'content-type: application/json' \
-d '{ "companyId": "<uuid>", "email": "admin@clinica.example", "password": "********" }'json
{
"accessToken": "eyJ…",
"refreshToken": "eyJ…",
"user": { "id": "…", "email": "…", "fullName": "…", "roles": ["admin"], "permissions": ["*"] }
}Como nomear a empresa: em modo local,
companyIdé ignorado (vem do.env). Online, informecompanyIdou oslugdo subdomínio — também aceito no headerX-Tenant-Slug.
Sessões e refresh
Cada login cria uma sessão (o refresh token é guardado só como hash, com validade, IP e dispositivo). O refresh valida o token, confere que a sessão não foi revogada nem expirou, recarrega roles/permissões e devolve um novo access token — então mudança de papel passa a valer sem novo login. Logout revoga a sessão do refresh token.
bash
curl -X POST $BASE/api/auth/refresh -H 'content-type: application/json' \
-d '{ "refreshToken": "eyJ…" }'POST /api/auth/validate-session verifica um access token offline (sem ida à nuvem), útil para checagem local de sessão.
Tokens
Access e refresh usam segredos separados (JWT_ACCESS_SECRET / JWT_REFRESH_SECRET), então um access token vazado não gera refresh. Os claims carregam sub, companyId, email, roles, permissions e o type (access/refresh) — um token usado como o tipo errado é rejeitado.
Referência de engenharia. Sessão, refresh, fluxos de senha, RBAC (papéis/permissões, guards e decorators) e a relação com multi-tenancy e auditoria estão consolidados em
docs/auth.md.
Senhas
- Troca de senha (
change-password, autenticado): confere a senha atual, grava o novo hash (bcrypt) e revoga todas as sessões do usuário. É o fluxo de senha completo hoje. - Reset (
forgot-password): apenas online (depende de e-mail) e responde sem revelar se o e-mail existe. A entrega do e-mail e a etapa de confirmação são integração futura.
Papéis e permissões (RBAC)
A autorização é decidida sempre no backend; o frontend nunca decide acesso. O token carrega as permissões achatadas a partir dos papéis do usuário. Veja Roles & permissões para o catálogo e os papéis de sistema.