Inicio de sesión único (SAML)

​

Cómo funciona

1. Su IdP autentica al médico y firma una aserción SAML.
2. Su backend llama POST /v1/sso/exchange con la secret key de su institución y la aserción.
3. Telepatia verifica la firma, el emisor, la audiencia y la validez contra la configuración SAML de su institución, y devuelve un access token del médico más un refresh token.
4. Su backend llama la API con el token del médico y lo renueva con POST /v1/sso/refresh — sin nueva ida al IdP hasta que la cadena de refresh termina.

​

Requisitos previos

• Una secret key de institución (sk_…) creada con el permiso SAML SSO exchange (la casilla saml:exchange en la página de API Keys de la plataforma).
• La configuración SAML guardada en la pestaña Developers → SSO de la plataforma: el entity ID (emisor) de su IdP y su certificado de firma.
• El médico ya debe existir en su institución. El SSO autentica médicos; no los crea.

​

Datos del Service Provider

​

Intercambiar una aserción

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 de la aserción

• La aserción está firmada (RSA-SHA256, firma envuelta) con el certificado configurado para su institución.
• El Issuer es igual al entity ID del IdP configurado para su institución.
• El Audience es igual al SP entity ID de arriba.
• El Destination es igual a la ACS URL de arriba.
• La ventana de validez (NotBefore / NotOnOrAfter) cubre el momento del intercambio.
• La aserción incluye un AttributeStatement — los IdP estándar siempre lo incluyen.
• El email del médico llega como NameID del sujeto (formato emailAddress), o en el atributo indicado por el ajuste opcional email attribute.

​

Renovar la sesión

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

​

Llamar la API como el médico

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

​

Respuestas de error

​

Ejemplo: aserción reutilizada

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

​

Ejemplo: aserción inválida

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