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

# Autenticación

> Cómo autenticarse con la Scribe API

Todos los endpoints de la Scribe API requieren autenticación mediante una clave API enviada como token Bearer en el encabezado `Authorization`.

## Tipos de clave

Al crear una cuenta de médico se devuelven **dos** claves API:

* **Clave secreta** (`sk_…`) — su credencial del lado del servidor. Úsela como token `Authorization: Bearer` en **todas** las solicitudes de esta documentación. Manténgala en su backend; nunca la exponga en un navegador.
* **Clave publicable** (`pk_…`) — una credencial de navegador para el grabador embebible de Telepatia. Es **solo de intercambio**: el embed la intercambia por un token de sesión de corta duración que lleva el acceso de lectura y escritura de su cuenta. Una clave `pk_` **no puede llamar directamente a la Scribe API** — presentarla como token Bearer en cualquier endpoint devuelve `403 permission_denied`.

Salvo que se indique lo contrario, "clave API" en esta documentación se refiere a su clave **secreta**.

## Obtener su clave API

Contacte a su gerente de cuenta de Telepatia para obtener una clave API para su institución.

## Realizar solicitudes autenticadas

Incluya la clave API en cada solicitud:

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer SU_CLAVE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "idCountry": "CO",
    "idType": "CC",
    "idValue": "123456789",
    "notes": "Patient reports headache",
    "pastMedicalHistory": "Hypertension, Diabetes Type 2",
    "consultationInternalId": "CONSULT-12345",
    "scribeSessionModality": "IN_PERSON"
  }'
```

Consulte la [descripción general](/es/scribe-api/index) para la URL base.

## Vencimiento de la clave API

Las claves API vencen. Las claves institucionales se generan con una vigencia (predeterminada: **365 días**, configurable mediante `apiKeyConfig.validForDays` al [crear una cuenta](/es/scribe-api/accounts#crear-una-cuenta)). Una vez que una clave supera su vencimiento, las solicitudes fallan con `401` y la misma respuesta *"Invalid API key."* que una clave revocada o desconocida. Para restaurar el acceso, [regenere la clave de la cuenta](/es/scribe-api/accounts#regenerar-una-clave-api) y actualice su integración con el nuevo valor.

## Respuestas de error

| Código | Significado                                       |
| ------ | ------------------------------------------------- |
| `401`  | Clave API faltante o inválida                     |
| `403`  | La clave API no tiene permiso para esta operación |

### Ejemplo: Clave API faltante

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "API key is required."
  }
}
```

### Ejemplo: Clave API inválida

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid API key."
  }
}
```

### Ejemplo: Clave publicable usada directamente

Una clave publicable (`pk_`) no puede llamar directamente a la API — intercámbiela primero por un token de sesión, o use su clave secreta.

```json theme={null}
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "Publishable keys cannot call the API directly; exchange one for a session token first, or use a secret key."
  }
}
```