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

# Cuentas

> Gestionar cuentas de médicos en su institución (solo claves API institucionales)

<Note>
  La gestión de cuentas solo está disponible con una **clave API institucional**. Las claves API de nivel médico no tienen acceso a estos endpoints.
</Note>

Las claves API institucionales pueden crear y recuperar cuentas de médicos dentro de su organización. Cada cuenta representa a un médico que puede usar el scribe de Telepatia a través de su integración. Crear una cuenta genera **dos** claves para esa cuenta — una clave **secreta** (`sk_…`) para las llamadas API del lado del servidor y una clave **publicable** (`pk_…`) para el embed de navegador (vea [Tipos de clave](/es/scribe-api/authentication#tipos-de-clave)). Puede rotar la clave secreta más adelante.

## Crear una cuenta

`POST /v1/institutional/accounts` requiere `email` y `doctorSpecialties`. Opcionalmente, envíe `apiKeyConfig.validForDays` (1–365) para controlar cuánto tiempo permanece válida la clave API generada; omítalo para usar el valor predeterminado de 365 días (1 año).

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts \
  -H "Authorization: Bearer SU_CLAVE_API_INSTITUCIONAL" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dr.juan@clinica.com",
    "doctorSpecialties": ["cardiology"],
    "nameFull": "Dr. Juan Pérez",
    "internalCode": "DOC-001",
    "apiKeyConfig": { "validForDays": 365 }
  }'
```

**Respuesta:**

```json theme={null}
{
  "id": "acc_a1b2c3d4e5f6g7h8",
  "email": "dr.juan@clinica.com",
  "apiKey": "<shown-once-store-securely>",
  "publishableApiKey": "<shown-once-store-securely>",
  "internalCode": "DOC-001",
  "expiresAt": "2027-06-17T00:00:00Z",
  "apiKeyExpiresInDays": 365
}
```

<Warning>
  `apiKey` (secreta) y `publishableApiKey` (publicable) se devuelven **solo una vez** — guárdelas de forma segura. `expiresAt` es la marca de tiempo UTC en que las claves dejan de funcionar, y `apiKeyExpiresInDays` refleja la vigencia que se aplicó. Use la clave secreta para las llamadas API del lado del servidor; la clave publicable es para el embed de navegador y no puede llamar directamente a la API.
</Warning>

Guarde el `id` (o su `internalCode`) — puede usar cualquiera de los dos para recuperar la cuenta más adelante.

## Recuperar una cuenta

Busque una cuenta por su `id` (`acc_*`) o por su propio `internalCode`.

```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/institutional/accounts/acc_a1b2c3d4e5f6g7h8 \
  -H "Authorization: Bearer SU_CLAVE_API_INSTITUCIONAL"
```

**Respuesta:**

```json theme={null}
{
  "id": "acc_a1b2c3d4e5f6g7h8",
  "email": "dr.juan@clinica.com",
  "nameFull": "Dr. Juan Pérez",
  "doctorSpecialties": ["CARDIOLOGY"],
  "enabled": true,
  "internalCode": "DOC-001",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

## Regenerar una clave API

Rote la clave API de una cuenta con `POST /v1/institutional/accounts/{account_id}/api-keys/regenerate`, identificando la cuenta por su `id` (`acc_*`) o `internalCode`. Opcionalmente, envíe `validForDays` (1–365) para definir la vigencia de la nueva clave; omítalo para mantener el valor predeterminado de la cuenta.

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/institutional/accounts/acc_a1b2c3d4e5f6g7h8/api-keys/regenerate \
  -H "Authorization: Bearer SU_CLAVE_API_INSTITUCIONAL" \
  -H "Content-Type: application/json" \
  -d '{ "validForDays": 365 }'
```

**Respuesta:**

```json theme={null}
{
  "accountId": "acc_a1b2c3d4e5f6g7h8",
  "apiKey": "<shown-once-store-securely>",
  "id": "ak_a1b2c3d4e5f6g7h8",
  "prefix": "sk_prod_a1b2c3d4...e5f6",
  "mode": "prod",
  "expiresAt": "2027-01-15T10:30:00Z"
}
```

<Warning>
  Regenerar revoca la clave anterior (tras un breve período de gracia) y devuelve la nueva `apiKey` sin cifrar **una sola vez** — actualice su integración antes de que termine el período de gracia. La regeneración está limitada a **una por cuenta cada 2 minutos**; excederla devuelve `429 rate_limit_exceeded`. Consulte [Manejo de errores](/es/scribe-api/errors#errores-de-clave-api).
</Warning>