Skip to main content

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).

Não existe POST /auth/login nem POST /auth/refresh

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.

Roles e permissões ficam em /roles

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:

OrdemHeaderEstratégiaUso típico
1x-api-keyAPI KeyIntegrações externas/servidor a servidor
2Authorization: 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:

  1. Decodifica o header do token para pegar o kid (key id).
  2. Busca a chave pública correspondente no JWKS do provedor, com cache.
  3. Verifica assinatura, validade e issuer.
  4. 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, 401 com "Token sem clínica selecionada".
  5. Confere se a sessão (sid) foi encerrada (logout ou revogação) — se sim, 401 com "Sessão encerrada".
  6. Confere se o vínculo do usuário com a clínica está bloqueado — se sim, 401 com "Usuário desativado".
  7. Confere se a clínica está ativa — se não, 401 com "Conta desativada".
  8. Busca no provedor as permissões do usuário nesta clínica (com cache de até 5 minutos).
O token não carrega as permissões

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çãoResposta
Token sem kid no header, sem sid ou não decodificável401 — "Token inválido"
Assinatura ou issuer inválidos, token expirado401 — "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 inteiros401 — "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 bloqueado401 — "Usuário desativado"
Clínica desativada ou excluída401 — "Conta desativada"
Provedor de identidade, Redis ou banco fora do ar durante a validação503 — "Não foi possível validar a sessão. Tente novamente em instantes."
503 não é sessão caída

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.

Rotas que dependem do usuário

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çãoResposta
Chave válida, com a permissão da rotaResposta normal da rota
Chave válida, sem a permissão da rota403 — "Permissões insuficientes"
Chave inválida ou revogada401 — "Credenciais inválidas"
Nenhum header de autenticação401 — "Credenciais não fornecidas"
Provedor de identidade fora do ar503

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".

RotaCom x-api-key
POST /triages403
POST /triages/{id}/decision403
PATCH /triages/{id}/decision403
PUT /triages/{id}/decision/diagnosis-draft403
POST /triages/{id}/documents403
POST /triages/{id}/interview403
POST /triages/{id}/interview/start401
POST /bugs403
GET /bugs/me403
GET /users/menão representa um usuário
POST /cash-management/opendepende do usuário do token
POST /cash-management/closedepende do usuário do token
PATCH /consultations/{id}/assigna 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 membershipId do 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".

Nomes de permissões

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
}