Pular para o conteúdo principal
Com o login único SAML a sua instituição tem uma API key em vez de uma key por médico. Seu provedor de identidade (Microsoft Entra ID, Okta, ADFS…) autentica o médico. A Telepatia recebe a resposta SAML assinada, devolve o navegador para a sua aplicação com um código de uso único, e seu backend troca esse código por um token de sessão do médico. Todos os endpoints de negócio continuam iguais. Só muda o valor de Authorization.

Como funciona

  1. Sua aplicação envia o navegador para GET /v1/sso/login/{institutionId} com um relayState gerado pela sua aplicação.
  2. A Telepatia envia o navegador para o seu provedor de identidade (IdP) com uma solicitação SAML.
  3. O médico faz login. O IdP envia (POST) a resposta SAML assinada para a URL de ACS da sua instituição na Telepatia, POST /v1/sso/acs/{institutionId}.
  4. A Telepatia verifica a resposta e redireciona o navegador (302) para a URL de retorno da sua instituição com ?code=…&state=….
  5. Seu backend compara state com o valor gerado no passo 1. Depois chama POST /v1/sso/token com a secret key da sua instituição e o code.
  6. A Telepatia devolve um access token do médico e um refresh token. Seu backend usa os dois na API e os renova com POST /v1/sso/refresh.
A resposta SAML nunca passa pelo seu backend, e a API key nunca passa pelo navegador.

Pré-requisitos

  • Uma secret key de instituição (sk_…) criada com a permissão SAML SSO exchange (a caixa saml:exchange na página de API Keys da plataforma).
  • Acesso a Plataforma → Developers → SSO. É de lá que você copia os valores da Telepatia.
  • Uma rota na sua aplicação que recebe o redirecionamento para a URL de retorno e consegue chamar a API pelo seu backend.
  • O médico já precisa existir na sua instituição, com o mesmo email que o seu IdP envia. O SSO autentica médicos; não os cria.

Dados do Service Provider

Copie estes valores do quadro Detalhes do provedor de serviços em Plataforma → Developers → SSO. Cada valor tem um botão para copiar. As URLs já trazem o ID da sua instituição. A Telepatia aceita uma resposta SAML só na URL de ACS da instituição a que a resposta se destina.

Configurar o seu provedor de identidade

Microsoft Entra ID

  1. No centro de administração do Entra, abra Enterprise applications → New application → Create your own application. Selecione Integrate any other application you don’t find in the gallery (Non-gallery).
  2. Abra Single sign-on e selecione SAML.
  3. Em Basic SAML Configuration, configure estes valores:
  4. Em Attributes & Claims, confirme que o Unique User Identifier (Name ID) é o email do médico, no formato Email address. O valor padrão é user.userprincipalname. Se o UPN dos seus usuários não for o email, use user.mail.
  5. Em SAML Certificates, baixe o Certificate (Base64). Copie também a App Federation Metadata Url.
  6. Em Set up sua aplicação, copie a Login URL e o Microsoft Entra Identifier.
  7. Em Users and groups, atribua os médicos que podem fazer login.
O Entra pode ler os valores da Telepatia de um arquivo. Baixe o arquivo da URL de metadados do SP e selecione Upload metadata file na página de Single sign-on.

Outros provedores de identidade

Use os mesmos dois valores: o ID de entidade do SP (público) é a audiência (Okta: Audience URI; ADFS: Relying party identifier), e a URL de ACS (URL de resposta) é o endereço que recebe a resposta SAML com o binding HTTP-POST (Okta: Single sign-on URL; ADFS: SAML Assertion Consumer endpoint). Envie o email do médico como NameID.

Configurar a plataforma

Em Plataforma → Developers → SSO, ative Ativar SSO SAML e salve estes valores:
Importar da URL de metadados do IdP preenche os campos do IdP a partir da App Federation Metadata Url do Entra. Revise os valores e cole o certificado antes de salvar.
Depois de salvar, o cartão de resumo mostra os valores salvos. Confira estas duas linhas:
  • URL de retorno: o seu endereço, ou Não configurada — o login pelo navegador está desativado.
  • Login iniciado pelo IdP: Permitido, ou Não permitido — apenas logins iniciados na Telepatia.
A plataforma salva todos os valores SAML juntos. Quando mudar um valor, revise a URL de retorno e a opção de login iniciado pelo IdP antes de salvar.

Iniciar o login

Envie o navegador para a URL de login que você copiou da plataforma e adicione ?relayState=. Neste exemplo, INSTITUTION_ID é o ID da sua instituição:
  • relayState é opcional, mas use. Gere um valor aleatório novo para cada login (por exemplo, 32 bytes aleatórios em base64url) e guarde na sessão do navegador do usuário na sua aplicação. A Telepatia devolve esse valor como state.
  • relayState pode ter no máximo 80 bytes. Não coloque dados pessoais nele.
  • O link não leva API key. A Telepatia envia o navegador para o seu IdP com um 302.
  • Tentativas demais de login a partir de uma mesma rede recebem 429 com um cabeçalho Retry-After.

Processar a URL de retorno

Depois que o médico faz login, a Telepatia envia o navegador para a sua URL de retorno:
A Telepatia mantém os parâmetros que a sua URL de retorno já tem. Ela substitui um code ou um state que já esteja nela. Na rota que recebe este redirecionamento:
  1. Compare state com o valor que você guardou no passo 1. Se estiver ausente ou for diferente, pare e mostre um erro.
  2. Remova o valor de state da sessão, para que ele seja usado uma única vez.
  3. Envie code para o seu backend e troque imediatamente.

Login iniciado pelo IdP

Um login também pode começar no IdP, por exemplo no portal My Apps do Entra. Nesse caso a Telepatia recebe uma resposta SAML sem uma solicitação SAML.
  • Quando Permitir login iniciado pelo IdP está desativado (o padrão), a Telepatia recusa essas respostas com a página de erro saml_idp_initiated_not_allowed.
  • Quando está ativado, a Telepatia envia o navegador para a sua URL de retorno com um code e sem state. A sua aplicação não iniciou esse login, então não tem um valor para comparar. Aceite só se a sua aplicação permitir logins que começam no IdP.
Para começar pelo bloco do My Apps sem ativar essa opção, configure a Sign on URL do Entra com a página de login da sua aplicação. Assim o bloco abre a sua aplicação, e a sua aplicação inicia o login com um state.

Trocar o código

Chame este endpoint pelo seu backend com a secret key da sua instituição:
Corpo da requisição:
Resposta 200:
  • documentId é a conta do médico.
  • expiresIn é a duração do access token, em segundos. Leia o valor em cada resposta. Não use um valor fixo no seu código.
  • O código vale por 90 segundos e para um único uso. Ele só funciona com uma key da instituição em que o médico fez login. Um código expirado, já usado ou desconhecido recebe 401.

Requisitos da asserção

  • A asserção é assinada (RSA-SHA256, assinatura envelopada) com o certificado configurado para a sua instituição.
  • O Issuer é igual ao entity ID do IdP configurado para a sua instituição.
  • O Audience é igual ao ID de entidade do SP acima.
  • O Destination e o Recipient são iguais à URL de ACS da sua instituição.
  • Quando o login começa em /v1/sso/login, a resposta traz o InResponseTo dessa solicitação SAML. Uma solicitação SAML vale por 5 minutos e para uma única resposta.
  • A janela de validade (NotBefore / NotOnOrAfter) cobre o momento em que a Telepatia recebe a resposta.
  • A asserção traz um AttributeStatement — IdPs padrão sempre incluem um.
  • O email do médico chega como NameID do sujeito (formato emailAddress), ou no atributo indicado pela configuração opcional email attribute.

Renovando a sessão

O refresh token é a credencial — sem key da instituição e sem código:
A resposta tem o mesmo formato de sessão de /v1/sso/token. Refresh tokens rotacionam: o antigo é revogado quando o novo par é emitido, e reutilizá-lo devolve 401.

Chamando a API como o médico

Use o access token exatamente onde iria a API key:

Notas de segurança

  • Verifique state. Compare com o valor que a sua aplicação guardou para esse navegador. Isso impede que um atacante envie uma vítima para a sua URL de retorno com o código do atacante.
  • Troque o código só no seu backend. A key sk_ nunca pode ir para o navegador. Não mostre o código, não registre em logs e não guarde depois da troca.
  • O código dura pouco. Ele vale por 90 segundos e para um único uso. Troque assim que a rota da sua URL de retorno receber o código.
  • Mantenha o login iniciado pelo IdP desativado se não precisar dele. Um login que a sua aplicação inicia traz state e um InResponseTo que a Telepatia verifica.
  • Guarde os tokens no seu backend. O access token e o refresh token dão acesso aos dados do médico.

Respostas de erro

Página de erro do login

/v1/sso/login e /v1/sso/acs respondem ao navegador, então um erro é uma página HTML e não JSON. A página mostra uma mensagem, um código de erro e um ID de requisição. Ela nunca redireciona para a sua URL de retorno. Informe o código e o ID de requisição ao suporte da Telepatia.

Erros da troca do código

/v1/sso/token responde ao seu backend com o formato de erro JSON:

Exemplo: código de login inválido

Migrar do /exchange

POST /v1/sso/exchange continua disponível, mas é o fluxo anterior. Seu backend precisa ter a resposta SAML assinada e enviá-la para a Telepatia. Um IdP padrão envia a resposta SAML para o navegador, então esse fluxo precisa de um endpoint SAML na sua aplicação. O fluxo desta página elimina esse endpoint.
  1. Na plataforma, configure a URL de SSO do IdP e a URL de retorno. Adicione a rota da URL de retorno na sua aplicação (veja Processar a URL de retorno).
  2. No seu IdP, adicione a URL de ACS (URL de resposta) da plataforma como Reply URL e marque como padrão. Mantenha a Reply URL anterior (/v1/sso/exchange) até terminar a troca.
  3. Mude o botão de login da sua aplicação para enviar o navegador para a URL de login, com ?relayState=STATE.
  4. Quando todos os logins usarem o fluxo novo, remova a Reply URL anterior e o código que chama /v1/sso/exchange.
A resposta com os tokens, a renovação e o token do médico são iguais nos dois fluxos.

Requisição de exchange anterior

O Destination de uma asserção para /v1/sso/exchange é https://scribe-api.telepatia.ai/v1/sso/exchange.
A resposta é igual à de /v1/sso/token. Cada asserção é de uso único. Uma segunda troca com a mesma asserção devolve 403.