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

# Authentication

> How to authenticate with the Scribe API

All Scribe API endpoints require authentication via an API key passed as a Bearer token in the `Authorization` header.

## Key types

Creating a doctor account returns **two** API keys:

* **Secret key** (`sk_…`) — your server-side credential. Use it as the `Authorization: Bearer` token for **every** request in this documentation. Keep it on your backend; never expose it in a browser.
* **Publishable key** (`pk_…`) — a browser credential for the Telepatia embeddable recorder. It is **exchange-only**: the embed trades it for a short-lived session token that carries your account's read and write access. A `pk_` key **cannot call the Scribe API directly** — presenting it as a Bearer token to any endpoint returns `403 permission_denied`.

Unless noted otherwise, "API key" in this documentation refers to your **secret** key.

## Getting your API key

Contact your Telepatia account manager to obtain an API key for your institution.

## Making authenticated requests

Include the API key in every request:

```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/set-consultation-context \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -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"
  }'
```

See [Overview](/scribe-api/index) for the base URL.

## API key expiration

API keys expire. Institutional keys are minted with a lifetime (default **365 days**, configurable via `apiKeyConfig.validForDays` when [creating an account](/scribe-api/accounts#creating-an-account)). Once a key is past its expiry, requests fail with `401` and the same *"Invalid API key."* response as a revoked or unknown key. To restore access, [regenerate the account's key](/scribe-api/accounts#regenerating-an-api-key) and update your integration with the new value.

## Error responses

| Status | Meaning                                             |
| ------ | --------------------------------------------------- |
| `401`  | Missing or invalid API key                          |
| `403`  | API key does not have permission for this operation |

### Example: Missing API key

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

### Example: Invalid API key

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

### Example: Publishable key used directly

A publishable (`pk_`) key cannot call the API directly — exchange it for a session token first, or use your secret key.

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