Visão Geral da Autenticação
A API não possui rotas de login ou de refresh de token — a autenticação é feita inteiramente por um provedor de identidade externo (WorkOS, via OAuth 2.0 / OIDC). O backend só valida o token que o cliente já obteve desse provedor (ou uma API Key, para integrações).
O login acontece direto no provedor de identidade (tela de login hospedada / SDK do frontend). Esta API nunca recebe email/senha — ela só recebe o accessToken já emitido pelo provedor e o valida a cada requisição.
O grupo /auth tem só o logout. A gestão de roles, permissões e atribuições a usuários está em Roles da Conta (/roles).
Duas estratégias de autenticação
Toda rota (exceto as marcadas como públicas) exige um dos dois headers abaixo. A estratégia é detectada automaticamente pelo StrategyAuthGuard, nesta ordem:
| Ordem | Header | Estratégia | Uso típico |
|---|---|---|---|
| 1 | x-api-key | API Key | Integrações externas/servidor a servidor |
| 2 | Authorization: Bearer {accessToken} | JWT (provedor de identidade) | Frontend / usuários logados |
Se nenhum dos dois headers estiver presente, a resposta é 401 Unauthorized com a mensagem "Credenciais não fornecidas".
JWT (provedor de identidade)
O accessToken é um JWT RS256 assinado pelo provedor de identidade. A validação faz, nesta ordem:
- Decodifica o header do token para pegar o
kid(key id). - Busca a chave pública correspondente no JWKS do provedor, com cache.
- Verifica assinatura, validade e
issuer. - Lê do token a clínica (
accountId), o usuário (userId) e o vínculo do usuário com a clínica (membershipId). Sem os três,401com"Token sem clínica selecionada". - Confere se a sessão (
sid) foi encerrada (logout ou revogação) — se sim,401com"Sessão encerrada". - Confere se o vínculo do usuário com a clínica está bloqueado — se sim,
401com"Usuário desativado". - Confere se a clínica está ativa — se não,
401com"Conta desativada". - Busca no provedor as permissões do usuário nesta clínica (com cache de até 5 minutos).
O accessToken é pequeno de propósito: não traz a lista de permissões. O backend as consulta no provedor pelo membershipId do token. Mudanças de roles feitas pela API valem de imediato; mudanças feitas direto no painel do provedor valem quando o cache expira (até 5 minutos). O front lê a mesma lista em GET /users/me/permissions.
Erros possíveis ao validar um JWT:
| Situação | Resposta |
|---|---|
Token sem kid no header, sem sid ou não decodificável | 401 — "Token inválido" |
Assinatura ou issuer inválidos, token expirado | 401 — "Token inválido ou expirado" |
accountId, userId ou membershipId ausentes no token (usuário ainda sem clínica escolhida) | 401 — "Token sem clínica selecionada" |
accountId ou userId que não são números inteiros | 401 — "Token com accountId inválido" / "Token com userId inválido" |
| Sessão encerrada (logout) | 401 — "Sessão encerrada" |
| Vínculo do usuário com a clínica bloqueado | 401 — "Usuário desativado" |
| Clínica desativada ou excluída | 401 — "Conta desativada" |
| Provedor de identidade, Redis ou banco fora do ar durante a validação | 503 — "Não foi possível validar a sessão. Tente novamente em instantes." |
Falhas de infraestrutura na validação voltam 503, e não 401: o cliente deve tentar de novo, sem tratar como sessão expirada.
Encerramento de sessão
POST /auth/logout coloca a sessão do token na lista de sessões encerradas (até o vencimento do token) e a revoga no provedor. A partir daí, o accessToken que já estava em uso também passa a ser recusado ("Sessão encerrada"). Bloquear ou excluir um usuário pela API derruba as sessões abertas dele na clínica.
API Key
Alternativa ao JWT para integrações. Enviada no header x-api-key. A chave é emitida e validada pelo provedor de identidade, como uma chave da clínica (veja API Keys). O payload de autenticação resultante carrega accountId, o id da API Key e as permissões da chave (sem userId, sub ou membershipId). Chave inexistente, revogada ou de clínica desativada → 401 — "Credenciais inválidas". Provedor fora do ar → 503.
A validação de uma chave fica em cache de curta duração (cerca de 60 segundos para chaves válidas e 10 segundos para inválidas); revogar pela API limpa o cache na hora.
Como a API Key não carrega userId, rotas que usam o usuário logado (ex.: GET /users/me, abrir caixa) ou que conferem payload.permissions dentro do serviço (ex.: atribuir usuário a consulta) não funcionam como esperado com API Key.
Exemplo
Qualquer rota que aceite API Key é chamada da mesma forma que com token, trocando o header:
curl -X 'GET' \
'https://api-dev.imagemais.com.br/api/procedures?limit=10' \
-H 'accept: application/json' \
-H 'x-api-key: {apiKey}'
| Situação | Resposta |
|---|---|
| Chave válida, com a permissão da rota | Resposta normal da rota |
| Chave válida, sem a permissão da rota | 403 — "Permissões insuficientes" |
| Chave inválida ou revogada | 401 — "Credenciais inválidas" |
| Nenhum header de autenticação | 401 — "Credenciais não fornecidas" |
| Provedor de identidade fora do ar | 503 |
Rotas que não aceitam API Key
Estas rotas exigem o token de um usuário (Authorization: Bearer). A página de cada uma traz o aviso "Só com token de usuário".
| Rota | Com x-api-key |
|---|---|
POST /triages | 403 |
POST /triages/{id}/decision | 403 |
PATCH /triages/{id}/decision | 403 |
PUT /triages/{id}/decision/diagnosis-draft | 403 |
POST /triages/{id}/documents | 403 |
POST /triages/{id}/interview | 403 |
POST /triages/{id}/interview/start | 401 |
POST /bugs | 403 |
GET /bugs/me | 403 |
GET /users/me | não representa um usuário |
POST /cash-management/open | depende do usuário do token |
POST /cash-management/close | depende do usuário do token |
PATCH /consultations/{id}/assign | a checagem interna sempre falha |
Permissões (@CheckPermissions e @CheckAnyPermissions)
Rotas marcadas com @CheckPermissions('permissao_x', 'permissao_y') exigem todas as permissões listadas, tanto com JWT quanto com API Key. Rotas marcadas com @CheckAnyPermissions(...) exigem qualquer uma delas.
Onde a checagem é feita:
- JWT: contra a lista de permissões do usuário nesta clínica, buscada no provedor de identidade pelo
membershipIddo token (com cache de até 5 minutos). Roles agrupam permissões, e o usuário pode ter várias roles: vale a soma delas. - API Key: contra as permissões da própria chave, definidas na criação.
Se faltar alguma permissão, a resposta é 403 Forbidden — "Permissões insuficientes".
Os nomes usam snake_case minúsculo (ex.: read_rapid_tests, create_procedures_groups). A lista completa está em Catálogo de Permissões.
Rotas públicas
Rotas marcadas com @IsPublic() pulam a autenticação inteiramente (StrategyAuthGuard retorna true sem checar nenhum header). No módulo de laboratórios, por exemplo, nenhuma rota é pública, e em /auth nenhuma rota é pública: o logout exige estar autenticado.
Payload disponível nas rotas (@TokenPayloadParam())
Dentro de um controller, use o decorator @TokenPayloadParam() para acessar os dados extraídos do token/API Key:
async minhaRota(@TokenPayloadParam() payload: AuthPayload) {
payload.accountId; // sempre presente
payload.authType; // 'jwt' | 'api_key'
payload.permissions; // JWT: do provedor, pelo membershipId; API Key: da chave
payload.userId; // só JWT
payload.sub; // só JWT — id do usuário no provedor de identidade
payload.sid; // só JWT — sessão (é o que o logout encerra)
payload.orgId; // só JWT — Organization da clínica no provedor
payload.membershipId; // só JWT — vínculo do usuário com a clínica
payload.apiKeyUuid; // só API Key — id da chave
}