Skip to content

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étodoRotaAuthDescrição
POST/api/auth/loginpúblicaautentica e devolve access + refresh token
POST/api/auth/refreshpúblicatroca refresh token por novo access token
POST/api/auth/logoutpúblicarevoga a sessão de um refresh token
GET/api/auth/meBearerusuário autenticado atual (roles + permissões)
POST/api/auth/change-passwordBearertroca a senha (revoga as sessões)
POST/api/auth/forgot-passwordpúblicasolicita reset (apenas online)
POST/api/auth/validate-sessionpúblicavalida 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, informe companyId ou o slug do subdomínio — também aceito no header X-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.