🔑 Autenticação de usuários por sistema externo

Permite que a plataforma do cliente, que já autenticou o usuário do seu lado, abra uma sessão
para ele na Ensinio sem pedir login e senha.

O endpoint exige:

Authorization: Bearer {token}

Content-Type: application/json

Recurso do plano necessário:

Public API – Generate Session Code

Como funciona

sequenceDiagram
    actor U as Usuário
    participant E as Sistema externo
    participant B as Ensinio (API)
    participant F as Ensinio (front)

    U->>E: login na plataforma do cliente
    E->>B: POST /public/api/v1/auth/session-code<br/>Bearer {token da integração} + { email }
    B->>B: valida integração, usuário e elegibilidade
    B-->>E: { code, expires_in, redirect_url }
    E-->>U: redirect para redirect_url
    U->>F: GET /auth-token/token?token={code}
    F->>B: POST /api/v1/auth-factory-token { token }
    B->>B: consome o código (uso único)
    B-->>F: sessão + token do usuário
    F-->>U: dentro da plataforma, autenticado

O sistema externo só precisa implementar os dois primeiros passos: chamar o endpoint e
redirecionar para o redirect_url que vier na resposta. O resto acontece dentro da Ensinio.

🎟️ Emitir código

POST /auth/session-code

Body

{
  "email": "[email protected]"
}

200

{
  "code": "hRk2pQ9vTz8mXn4LbW1cJyF6sD0gA3eUoI7tZqPr",
  "expires_in": 120,
  "expires_at": "2026-09-22T14:32:10-03:00",
  "redirect_url": "https://sua-plataforma.ensinio.com/auth-token/token?token=hRk2pQ9vTz8mXn4LbW1cJyF6sD0gA3eUoI7tZqPr"
}

Redirecione o browser do usuário para redirect_url exatamente como veio. Não é preciso montar
a URL: o domínio do front não é o mesmo da API, e devolvê-la pronta evita o erro mais comum da
integração.

Exemplo

curl -X POST https://sua-plataforma.ensinio.cloud/public/api/v1/auth/session-code \
  -H "Authorization: Bearer {SEU_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

🔒 Garantias do código

Regra	Como é cumprida
Imprevisível	40 caracteres aleatórios criptográficos
Não carrega dado sensível	é opaco; nada do usuário pode ser lido a partir dele
Validade curta	120 segundos
Uso único	invalidado no próprio resgate, por escrita condicional no banco
Não recuperável a partir do banco	a Ensinio guarda apenas o hash SHA-256

O code aparece uma única vez, nesta resposta. Não há endpoint para consultá-lo depois.
Perdeu, emita outro — cada chamada gera um código novo e não reaproveita o anterior.

🚫 Quem não pode ser autenticado

O usuário System do tenant, em nenhuma circunstância.
Usuários que não têm acesso à plataforma.
Qualquer usuário, enquanto o tenant estiver bloqueado.

Não bloqueiam a emissão: e-mail não verificado e conta desativada. Verificar e-mail não é
obrigatório na plataforma, e quem chama a rota já autenticou o usuário do lado dele.

Respostas de erro

Código	Quando
`401`	token da integração ausente ou inválido
`403`	recurso Public API – Generate Session Code não habilitado no plano
`404`	usuário não encontrado ou não elegível
`422`	`email` ausente ou malformado
`429`	limite de requisições do plano excedido

O 404 é deliberadamente o mesmo para e-mail inexistente e usuário System.
Diferenciá-los transformaria o endpoint em ferramenta para descobrir quais e-mails existem na
base do tenant — e quais deles são privilegiados. Para provisionar um usuário que ainda não
existe, use POST /users antes.