Sessões e autenticação multifator

O COBRES mantém sessões de equipe e sessões Audience separadas. A escolha do fluxo depende da pessoa e da superfície acessada.

Equipe: console e backoffice

O login humano recebe e-mail, senha e plano de acesso. A API emite um token de acesso; a renovação usa cookie HttpOnly pela rota POST /api/v1/auth/refresh. O token de acesso não é uma chave de integração.

Políticas da organização podem exigir MFA, limitar métodos e definir modo de sessão. Uma credencial marcada como troca obrigatória precisa concluir a mudança de senha antes das operações protegidas. O backend responde com códigos específicos, como password_change_required, mfa_enrollment_required e mfa_challenge_required.

A pessoa pode consultar suas sessões em /api/v1/me/sessions. A administração de sessões de outro membro exige a permissão prevista para a organização. Revogar uma sessão ou bloquear a pessoa deve ser feito pelo fluxo próprio, não pela limpeza apenas do armazenamento local do navegador.

Portal do credor

O plano Audience usa EndUser, chave de assinatura própria e cookie de refresh sg_refresh_audience. O prefixo HTTP é /api/audience/v1.

O acesso é sem senha, por portas habilitadas como link de e-mail, código de e-mail e provedores sociais. Login por telefone e pré-cadastros dependem de capacidades e configuração; não presuma que estejam habilitados em toda organização.

Um identity JWT ou uma chave sgk_ não autentica no Audience. Da mesma forma, o token Audience não autentica nas rotas da equipe.

MFA e ações sensíveis no portal

O segundo fator opcional do Audience é TOTP. SMS, quando habilitado, é um método primário de entrada, e não o segundo fator.

Ações sensíveis, como exclusão da conta, configuração de MFA e determinadas mudanças de contatos, podem exigir autenticação recente. 403 recent_login_required pede reautenticação na mesma sessão. O cliente deve concluir essa etapa e repetir a intenção original; não deve executar envios automáticos de códigos ao montar uma tela.

Tratamento correto de falhas

Uma indisponibilidade de banco responde 503 unavailable, preservando a distinção de uma sessão recusada. Não encerre a sessão ao receber qualquer erro HTTP. Respeite Retry-After e acompanhe o código de erro.

As instruções operacionais de identidade do portal estão em RUNBOOK-AUDIENCE-IDENTITY.md, na raiz de application/.