Login único (SSO)

Como o fluxo funciona

Setas cheias são chamadas; tracejadas, respostas. No celular, arraste o diagrama para o lado.

1. O membro, já autenticado no seu app, abre a área de livros.
2. O app pede ao seu backend uma sessão Astorya. Seu backend identifica o membro pela sessão que você já controla e chama POST /partner/v1/sessions com a credencial.
3. A Astorya cria ou encontra o membro e responde com a launchUrl.
4. Seu backend devolve a launchUrl ao app (nunca a credencial).
5. O app abre a launchUrl numa WebView imediatamente.
6. O Astorya Web lê o token da URL, apaga-o da barra de endereço e troca-o por uma sessão do membro.
7. A sessão é criada; o token não serve mais para nada.
8. O Astorya Web envia o evento astorya:ready para o app (veja eventos da ponte) e o membro está dentro.

Criar uma sessão

{
  "externalUserId": "usuario-10293",
  "email": "maria@exemplo.com.br",
  "name": "Maria Souza",
  "redirectPath": "/biblioteca"
}

Resposta 201 Created:

Criação no primeiro acesso

Você não precisa cadastrar ninguém antes. Na primeira sessão pedida para um externalUserId desconhecido, a Astorya cria o membro na hora (just-in-time provisioning). Nas próximas, encontra a mesma conta — com biblioteca, progresso de leitura e escuta preservados.

• O externalUserId é único dentro do seu tenant. Dois parceiros diferentes podem usar o mesmo valor sem conflito.
• Membros criados pela integração não têm senha: entram sempre pelo seu app. Não existe tela de login para eles.
• Se você quiser criar ou atualizar o cadastro antes do primeiro acesso (por exemplo, ao contratar o plano), use PUT /users/{externalUserId}.

E-mail e vínculo de conta

• Sem e-mail: o membro é criado só com o externalUserId. Funciona normalmente.
• E-mail de uma conta que ainda não tem externalUserId no seu tenant: a conta existente é vinculada a esse externalUserId, e o membro mantém o histórico.
• E-mail que já pertence a outro membro, vinculado a um externalUserId diferente: a API responde 409 EMAIL_CONFLICT e nenhuma sessão é criada.

Abrir uma tela específica

Use redirectPath para levar o membro direto a uma tela. O caminho precisa começar com / (não com //); qualquer valor que não seja uma rota conhecida leva à tela inicial.

Quando o link expira

A launchUrl vale 60 segundos e só pode ser usada uma vez. Se a WebView abrir um link expirado, já usado ou inválido (por exemplo, o usuário voltou para uma aba antiga, ou o app recarregou a página com a mesma URL):

1. O Astorya Web mostra a tela “Link expirado — volte ao app e abra o Astorya de novo”, sem formulário de login.
2. Envia o evento astorya:session-expired com reason: "invalid_launch_token".
3. Seu app deve pedir uma nova sessão ao seu backend e carregar a nova launchUrl na mesma WebView.

O mesmo evento chega com reason: "refresh_failed" quando uma sessão longa termina durante o uso. O tratamento é idêntico. Se a falha for de rede, o token não é consumido e a tela oferece “Tentar de novo”.

Erros desta etapa

Lista completa em Erros.

Segurança da sua rota de sessão

A rota do seu backend que chama POST /sessions é, na prática, a porta de entrada do membro. Proteja-a como qualquer rota autenticada:

• Obtenha o externalUserId da sessão autenticada do seu app, nunca de um parâmetro enviado pelo cliente. Senão, qualquer pessoa poderia entrar como outro membro.
• Confira no seu sistema se o membro tem direito ao benefício antes de pedir a sessão.
• Devolva ao app só a launchUrl, e use HTTPS de ponta a ponta.