Authorization.
Como funciona
- Sua aplicação envia o navegador para
GET /v1/sso/login/{institutionId}com umrelayStategerado pela sua aplicação. - A Telepatia envia o navegador para o seu provedor de identidade (IdP) com uma solicitação SAML.
- 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}. - A Telepatia verifica a resposta e redireciona o navegador (
302) para a URL de retorno da sua instituição com?code=…&state=…. - Seu backend compara
statecom o valor gerado no passo 1. Depois chamaPOST /v1/sso/tokencom a secret key da sua instituição e ocode. - 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.
Pré-requisitos
- Uma secret key de instituição (
sk_…) criada com a permissão SAML SSO exchange (a caixasaml:exchangena 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
- 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).
- Abra Single sign-on e selecione SAML.
-
Em Basic SAML Configuration, configure estes valores:
-
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, useuser.mail. - Em SAML Certificates, baixe o Certificate (Base64). Copie também a App Federation Metadata Url.
- Em Set up sua aplicação, copie a Login URL e o Microsoft Entra Identifier.
- Em Users and groups, atribua os médicos que podem fazer login.
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 comoNameID.
Configurar a plataforma
Em Plataforma → Developers → SSO, ative Ativar SSO SAML e salve estes valores:
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.
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 comostate.relayStatepode 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
429com um cabeçalhoRetry-After.
Processar a URL de retorno
Depois que o médico faz login, a Telepatia envia o navegador para a sua URL de retorno:code ou um state que já esteja nela.
Na rota que recebe este redirecionamento:
- Compare
statecom o valor que você guardou no passo 1. Se estiver ausente ou for diferente, pare e mostre um erro. - Remova o valor de
stateda sessão, para que ele seja usado uma única vez. - Envie
codepara 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
codee semstate. 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.
state.
Trocar o código
Chame este endpoint pelo seu backend com a secret key da sua instituição: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
Destinatione oRecipientsão iguais à URL de ACS da sua instituição. - Quando o login começa em
/v1/sso/login, a resposta traz oInResponseTodessa 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
NameIDdo sujeito (formatoemailAddress), 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:/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
statee umInResponseToque 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.
- 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).
- 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. - Mude o botão de login da sua aplicação para enviar o navegador para a URL de login, com
?relayState=STATE. - Quando todos os logins usarem o fluxo novo, remova a Reply URL anterior e o código que chama
/v1/sso/exchange.
Requisição de exchange anterior
ODestination de uma asserção para /v1/sso/exchange é https://scribe-api.telepatia.ai/v1/sso/exchange.
/v1/sso/token. Cada asserção é de uso único. Uma segunda troca com a mesma asserção devolve 403.