Authorization.
Cómo funciona
- Tu aplicación envía el navegador a
GET /v1/sso/login/{institutionId}con unrelayStateque generó tu aplicación. - Telepatia envía el navegador a tu proveedor de identidad (IdP) con una solicitud SAML.
- El médico inicia sesión. El IdP envía (POST) la respuesta SAML firmada a la URL de ACS de tu institución en Telepatia,
POST /v1/sso/acs/{institutionId}. - Telepatia verifica la respuesta y redirige el navegador (
302) a la URL de retorno de tu institución con?code=…&state=…. - Tu backend compara
statecon el valor que generó en el paso 1. Luego llama aPOST /v1/sso/tokencon la clave secreta de tu institución y elcode. - Telepatia devuelve un access token del médico y un refresh token. Tu backend los usa en la API y los renueva con
POST /v1/sso/refresh.
Requisitos previos
- Una clave secreta de institución (
sk_…) creada con el permiso SAML SSO exchange (la casillasaml:exchangeen la página de API Keys de la plataforma). - Acceso a Plataforma → Developers → SSO. Desde ahí copias los valores de Telepatia.
- Una ruta en tu aplicación que reciba la redirección a la URL de retorno y que pueda llamar a la API desde tu backend.
- El médico ya debe existir en tu institución, con el mismo email que envía tu IdP. El SSO autentica médicos; no los crea.
Datos del Service Provider
Copia estos valores del recuadro Detalles del proveedor de servicios en Plataforma → Developers → SSO. Cada valor tiene un botón para copiarlo. Las URL ya incluyen el ID de tu institución.
Telepatia acepta una respuesta SAML solo en la URL de ACS de la institución a la que corresponde la respuesta.
Configurar tu proveedor de identidad
Microsoft Entra ID
- En el centro de administración de Entra, abre Enterprise applications → New application → Create your own application. Selecciona Integrate any other application you don’t find in the gallery (Non-gallery).
- Abre Single sign-on y selecciona SAML.
-
En Basic SAML Configuration, configura estos valores:
-
En Attributes & Claims, verifica que el Unique User Identifier (Name ID) sea el email del médico, con el formato Email address. El valor predeterminado es
user.userprincipalname. Si el UPN de tus usuarios no es su email, usauser.mail. - En SAML Certificates, descarga Certificate (Base64). Copia también la App Federation Metadata Url.
- En Set up tu aplicación, copia la Login URL y el Microsoft Entra Identifier.
- En Users and groups, asigna los médicos que pueden iniciar sesión.
Otros proveedores de identidad
Usa los mismos dos valores: el ID de entidad del SP (audiencia) es la audiencia (Okta: Audience URI; ADFS: Relying party identifier), y la URL de ACS (URL de respuesta) es la dirección que recibe la respuesta SAML con el binding HTTP-POST (Okta: Single sign-on URL; ADFS: SAML Assertion Consumer endpoint). Envía el email del médico comoNameID.
Configurar la plataforma
En Plataforma → Developers → SSO, activa Activar SSO SAML y guarda estos valores:
Después de guardar, la tarjeta de resumen muestra los valores guardados. Revisa estas dos filas:
- URL de retorno: tu dirección, o Sin configurar — el inicio de sesión en el navegador está apagado.
- Inicio de sesión iniciado por el IdP: Permitido, o No permitido — solo inicios de sesión iniciados en Telepatia.
Iniciar la sesión
Envía el navegador a la URL de inicio de sesión que copiaste de la plataforma y agrega?relayState=. En este ejemplo, INSTITUTION_ID es el ID de tu institución:
relayStatees opcional, pero úsalo. Genera un valor aleatorio nuevo para cada inicio de sesión (por ejemplo, 32 bytes aleatorios en base64url) y guárdalo en la sesión del navegador del usuario en tu aplicación. Telepatia te lo devuelve comostate.relayStatepuede tener como máximo 80 bytes. No pongas datos personales en él.- El enlace no lleva API key. Telepatia envía el navegador a tu IdP con un
302. - Demasiados intentos de inicio de sesión desde una misma red reciben
429con un encabezadoRetry-After.
Procesar la URL de retorno
Después de que el médico inicia sesión, Telepatia envía el navegador a tu URL de retorno:code o un state que ya esté en ella.
En la ruta que recibe esta redirección:
- Compara
statecon el valor que guardaste en el paso 1. Si falta o es diferente, detén el proceso y muestra un error. - Elimina el valor de
statede la sesión, para que se use una sola vez. - Envía
codea tu backend y canjéalo de inmediato.
Inicio de sesión desde el IdP
Un inicio de sesión también puede empezar en el IdP, por ejemplo desde el portal My Apps de Entra. En ese caso Telepatia recibe una respuesta SAML sin una solicitud SAML.- Cuando Permitir inicio de sesión iniciado por el IdP está desactivado (el valor por defecto), Telepatia rechaza estas respuestas con la página de error
saml_idp_initiated_not_allowed. - Cuando está activado, Telepatia envía el navegador a tu URL de retorno con un
codey sinstate. Tu aplicación no inició este proceso, así que no tiene un valor para comparar. Acéptalo solo si tu aplicación permite inicios de sesión que empiezan en el IdP.
state.
Canjear el código
Llama a este endpoint desde tu backend con la clave secreta de tu institución:200:
documentIdes la cuenta del médico.expiresInes la vida del access token, en segundos. Léelo en cada respuesta. No uses un valor fijo en tu código.- El código es válido por 90 segundos y para un solo uso. Solo funciona con una clave de la institución en la que el médico inició sesión. Un código vencido, ya usado o desconocido recibe
401.
Requisitos de la aserción
- La aserción está firmada (RSA-SHA256, firma envuelta) con el certificado configurado para tu institución.
- El
Issuercoincide con el entity ID del IdP configurado para tu institución. - El
Audiencecoincide con el ID de entidad del SP indicado arriba. - El
Destinationy elRecipientcoinciden con la URL de ACS de tu institución. - Cuando el inicio de sesión empieza en
/v1/sso/login, la respuesta lleva elInResponseTode esa solicitud SAML. Una solicitud SAML es válida por 5 minutos y para una sola respuesta. - La ventana de validez (
NotBefore/NotOnOrAfter) cubre el momento en que Telepatia recibe la respuesta. - La aserción incluye un
AttributeStatement; los IdP estándar siempre lo incluyen. - El email del médico llega como
NameIDdel sujeto (formatoemailAddress), o en el atributo indicado por el ajuste opcional email attribute.
Renovar la sesión
El refresh token es la credencial; no se envían la clave de la institución ni el código:/v1/sso/token. Los refresh tokens rotan: el anterior se revoca cuando se emite el par nuevo, y reutilizarlo devuelve 401.
Llamar a la API como el médico
Usa el access token exactamente donde iría la API key:Notas de seguridad
- Verifica
state. Compáralo con el valor que tu aplicación guardó para ese navegador. Así evitas que un atacante envíe a una víctima a tu URL de retorno con el código del atacante. - Canjea el código solo en tu backend. La clave
sk_nunca debe llegar al navegador. No muestres el código, no lo registres en logs y no lo guardes después de canjearlo. - El código dura poco. Es válido por 90 segundos y para un solo uso. Canjéalo apenas la ruta de tu URL de retorno lo reciba.
- Mantén desactivado el inicio de sesión desde el IdP si no lo necesitas. Un inicio de sesión que empieza tu aplicación lleva
statey unInResponseToque Telepatia verifica. - Guarda los tokens en tu backend. El access token y el refresh token dan acceso a los datos del médico.
Respuestas de error
Página de error del inicio de sesión
/v1/sso/login y /v1/sso/acs le responden al navegador, así que un error es una página HTML y no JSON. La página muestra un mensaje, un código de error y un ID de solicitud. Nunca redirige a tu URL de retorno. Comparte el código y el ID de solicitud con el soporte de Telepatia.
Errores del canje del código
/v1/sso/token le responde a tu backend con el formato de error JSON:
Ejemplo: código de inicio de sesión inválido
Migrar desde /exchange
POST /v1/sso/exchange sigue disponible, pero es el flujo anterior. Tu backend debe tener la respuesta SAML firmada y enviarla a Telepatia. Un IdP estándar envía la respuesta SAML al navegador, así que este flujo necesita un endpoint SAML en tu aplicación. El flujo de esta página elimina ese endpoint.
- En la plataforma, configura la URL de SSO del IdP y la URL de retorno. Agrega a tu aplicación la ruta de la URL de retorno (consulta Procesar la URL de retorno).
- En tu IdP, agrega la URL de ACS (URL de respuesta) de la plataforma como Reply URL y márcala como predeterminada. Conserva la Reply URL anterior (
/v1/sso/exchange) hasta terminar el cambio. - Cambia el botón de inicio de sesión de tu aplicación para que envíe el navegador a la URL de inicio de sesión, con
?relayState=STATE. - Cuando todos los inicios de sesión usen el flujo nuevo, elimina la Reply URL anterior y el código que llama a
/v1/sso/exchange.
Solicitud de exchange anterior
ElDestination de una aserción para /v1/sso/exchange es https://scribe-api.telepatia.ai/v1/sso/exchange.
/v1/sso/token. Cada aserción es de un solo uso. Un segundo intercambio con la misma aserción devuelve 403.