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

# Authentication

> Authenticate server requests with an organization API key.

## Create a key

An Org Admin creates a key under **Settings → API Keys** in the dashboard. The
raw key is shown once and starts with `dh_`. Store it in a secret manager and
use it only from a trusted server. Never put it in browser code, a mobile
application, a URL, or a source repository.

## Send the key

Send the key on every request. The recommended header is:

```http theme={null}
Authorization: Bearer dh_your_api_key
```

The following header is also supported:

```http theme={null}
x-api-key: dh_your_api_key
```

Do not send a browser session cookie with an organization key. A request that
presents more than one credential is refused.

## What a key represents

A key authenticates *the organization*, not the person who created it. It
carries `call_logs.view` and `chat_logs.view` and nothing else, and no
lifecycle event on its creator (a role change, a password reset, a removed
membership, a deleted account) changes what it reaches. Revoking the key is the
only thing that stops it.

To replace a key, create a new one, update your server's secret, confirm a
request, and then revoke the old key.

## Tenant selection

Requests may name an organization or a workspace, through a header or a query
parameter:

```http theme={null}
Organization: 6f1e2d3c-4b5a-4c6d-8e9f-0a1b2c3d4e5f
```

```text theme={null}
?organization_id=6f1e2d3c-4b5a-4c6d-8e9f-0a1b2c3d4e5f&workspace_id=...
```

Selectors are optional because the key already identifies its organization.
When supplied, they must match the key. A selector narrows; it never widens.
Anything else is refused: a foreign caregiver, chat, call, phone number,
workspace, or organization in a header, body field, query string, or path
simply does not resolve.

## When a request is refused

These refusals happen before the endpoint runs. They return `403 Forbidden`
with a `detail` message instead of the standard response envelope:

```json theme={null}
{ "detail": "Unauthorized" }
```

| Cause | `detail` |
| - | - |
| The key is invalid or revoked | `Unauthorized` |
| No credential was sent | `Authentication credentials were not provided.` |
| More than one credential was presented | `More than one credential was presented. Send an organization key or a session token, not both.` |
| A selector names a different organization | `This key belongs to a different organization than the request selected.` |
| The endpoint is not available to organization keys | `An organization API key cannot be used on this endpoint.` |

A record your organization does not own is not refused this way. It reads as
"not found" in the standard envelope, so a caller is never told whether it
exists in another organization.

## What a key cannot do

Organization keys are refused on every route not in the
[API reference](https://docs.drivehealth.ai/api-reference/overview.md): key management, team and
invitations, passwords, sub-organizations, workspaces, caregiver and patient
management, platform configuration, audit logs, internal service routes, and
impersonation. Those need a person signed in to the dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.