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

# Authentication

> How to authenticate with the Healos External API

# Authentication

All requests must include a valid API key in the `X-API-Key` header.

```bash theme={null}
curl -H "X-API-Key: hlsk_your_key_here" \
  https://api.healos.ai/ext-api/v1/patients
```

## Prerequisites

* You must belong to an **organization**. If you don't have one, create one first from the Healos dashboard.
* Only **organization admins** can create, list, and revoke API keys.

## Obtaining an API Key

Create API keys by making an authenticated `POST` request to `/api/v1/ext-api-keys` from a logged-in Healos session. You must be an org admin. The response includes the raw key — **store it securely**, as it cannot be retrieved again.

API keys are prefixed with `hlsk_` and are tied to your organization. All data accessed through the key is scoped to your organization — you can read and write patients, appointments, and documents, list the providers in your organization, and read clinical notes belonging to any member of your org. A single key covers every provider in the organization; you assign records to specific providers with the `provider_id` field rather than issuing a key per provider.

## Scopes

Each API key has a set of scopes that control resource access. Scopes follow a `resource:action` pattern.

| Scope                | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `*`                  | Full access to all resources                         |
| `patients:read`      | Read patient data                                    |
| `patients:write`     | Create, update, delete patients                      |
| `appointments:read`  | Read appointments                                    |
| `appointments:write` | Create, update, delete appointments                  |
| `documents:read`     | Read documents                                       |
| `documents:write`    | Upload and delete documents                          |
| `notes:read`         | Read and export clinical notes                       |
| `providers:read`     | List the providers (clinicians) in your organization |

<Note>
  `GET` and `HEAD` requests require `read` scopes. All other methods (`POST`, `PATCH`, `DELETE`) require `write` scopes.
</Note>

## Key Expiration and Revocation

* Keys can have an optional expiration timestamp set at creation.
* Keys can be revoked at any time.
* Expired or revoked keys return `401 Unauthorized`.

## Security Best Practices

* Use the **narrowest scopes** needed for your integration.
* Set an **expiration date** on keys used in less-trusted environments.
* **Rotate keys** periodically and revoke old ones.
* Never expose keys in client-side code or public repositories.