> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Inicio de sesión único (SAML)

> Intercambie la API key de su institución más una aserción SAML por una sesión de médico

Con el inicio de sesión único SAML su institución tiene **una** API key en lugar de una key por médico. Su proveedor de identidad (Okta, Azure AD, ADFS…) autentica al médico, y su backend intercambia la key de la institución más una aserción SAML firmada por un **token de sesión del médico**. Todos los endpoints de negocio siguen iguales — solo cambia el valor de `Authorization`.

## 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

Registre estos valores fijos de Telepatia en su proveedor de identidad. Son los mismos para todas las instituciones.

| Valor                            | URL                                               |
| -------------------------------- | ------------------------------------------------- |
| SP entity ID (audiencia)         | `https://scribe-api.telepatia.ai/saml`            |
| ACS URL (destino de la aserción) | `https://scribe-api.telepatia.ai/v1/sso/exchange` |
| URL de metadata del SP           | `https://scribe-api.telepatia.ai/v1/sso/metadata` |

## Intercambiar una aserción

Envíe la respuesta SAML codificada en base64 con la key de su institución:

```bash theme={null}
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..."
  }'
```

Respuesta `200`:

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

Guarde la sesión y reutilícela hasta que expire. Cada aserción es de **un solo uso** — un segundo intercambio con la misma aserción devuelve `403`.

## 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

El refresh token es la credencial — sin key de institución y sin aserción:

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

La respuesta trae la misma forma de sesión que el intercambio. Los refresh tokens **rotan**: el anterior se revoca cuando se emite el par nuevo, y reutilizarlo devuelve `401`.

## Llamar la API como el médico

Use el access token exactamente donde iría la API key:

```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/scribe-session-configurations \
  -H "Authorization: Bearer DOCTOR_ACCESS_TOKEN"
```

## Respuestas de error

| Código | Significado                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------- |
| `401`  | Key de institución inválida o expirada, o un refresh token ya rotado                                                |
| `403`  | SSO deshabilitado, key sin el permiso `saml:exchange`, aserción reutilizada, o médico no vinculado a la institución |
| `422`  | La aserción falló la verificación: firma, emisor, audiencia, destino, validez, o falta el `AttributeStatement`      |

### Ejemplo: aserción reutilizada

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

### Ejemplo: aserción inválida

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