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

# Accounts

> Manage doctor accounts under your institution (institutional API keys only)

<Note>
  Account management is only available with an **institutional API key**. Doctor-level API keys do not have access to these endpoints.
</Note>

Institutional API keys can create and retrieve doctor accounts within their organization. Each account represents a clinician who can use the Telepatia scribe through your integration. Creating an account mints **two** keys for that account — a **secret** key (`sk_…`) for server-side API calls and a **publishable** key (`pk_…`) for the browser embed (see [Key types](/scribe-api/authentication#key-types)). You can later rotate the secret key.

## Creating an account

`POST /v1/institutional/accounts` requires `email` and `doctorSpecialties`. Optionally pass `apiKeyConfig.validForDays` (1–365) to control how long the minted API key stays valid — omit it to default to 365 days (1 year).

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

**Response:**

```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` (secret) and `publishableApiKey` (publishable) are returned **only once** — store them securely. `expiresAt` is the UTC timestamp when the keys stop working, and `apiKeyExpiresInDays` echoes the lifetime that was applied. Use the secret key for server-side API calls; the publishable key is for the browser embed and cannot call the API directly.
</Warning>

Save the `id` (or your `internalCode`) — you can use either to retrieve the account later.

## Retrieving an account

Look up an account by its `id` (`acc_*`) or by your own `internalCode`.

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

**Response:**

```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"
}
```

## Regenerating an API key

Rotate an account's API key with `POST /v1/institutional/accounts/{account_id}/api-keys/regenerate`, identifying the account by its `id` (`acc_*`) or `internalCode`. Optionally pass `validForDays` (1–365) to set the new key's lifetime; omit it to keep the account's default.

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

**Response:**

```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>
  Regenerating revokes the previous key (after a short grace window) and returns the new raw `apiKey` **once** — update your integration before the grace window closes. Regeneration is limited to **one per account every 2 minutes**; exceeding it returns `429 rate_limit_exceeded`. See [Error Handling](/scribe-api/errors#api-key-errors).
</Warning>