Login único (SAML)

​

Como funciona

1. Seu IdP autentica o médico e assina uma asserção SAML.
2. Seu backend chama POST /v1/sso/exchange com a secret key da sua instituição e a asserção.
3. A Telepatia verifica a assinatura, o emissor, a audiência e a validade contra a configuração SAML da sua instituição, e devolve um access token do médico mais um refresh token.
4. Seu backend chama a API com o token do médico e o renova com POST /v1/sso/refresh — sem nova ida ao IdP até a cadeia de refresh terminar.

​

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).
• A configuração SAML salva na aba Developers → SSO da plataforma: o entity ID (emissor) do seu IdP e o certificado de assinatura dele.
• O médico já precisa existir na sua instituição. O SSO autentica médicos; não os cria.

​

Dados do Service Provider

​

Trocar uma asserção

curl -X POST https://scribe-api.telepatia.ai/v1/sso/exchange \
  -H "Authorization: Bearer YOUR_INSTITUTION_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "samlResponse": "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46..."
  }'

{
  "documentId": "acc_1234567890",
  "token": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600,
    "refreshToken": "4167f20c-d620-40c4-b0f3-8f2a1c9e7d55"
  }
}

​

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 SP entity ID acima.
• O Destination é igual à ACS URL acima.
• A janela de validade (NotBefore / NotOnOrAfter) cobre o momento da troca.
• A asserção inclui um AttributeStatement — IdPs padrão sempre incluem.
• O e-mail do médico chega como NameID do sujeito (formato emailAddress), ou no atributo indicado pelo ajuste opcional email attribute.

​

Renovar a sessão

curl -X POST https://scribe-api.telepatia.ai/v1/sso/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "4167f20c-d620-40c4-b0f3-8f2a1c9e7d55"
  }'

​

Chamar a API como o médico

curl https://scribe-api.telepatia.ai/v1/scribe-session-configurations \
  -H "Authorization: Bearer DOCTOR_ACCESS_TOKEN"

​

Respostas de erro

​

Exemplo: asserção reutilizada

{
  "error": {
    "type": "invalid_request_error",
    "code": "permission_denied",
    "message": "SAML assertion could not be exchanged for a session."
  }
}

​

Exemplo: asserção inválida

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "SAML assertion could not be exchanged for a session."
  }
}