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

# Authentication

> API key authentication, required headers, and security best practices.

The Max AI API uses **Bearer token authentication** with API keys. Every request must include two required headers.

## Required Headers

| Header              | Required | Description                                             |
| ------------------- | -------- | ------------------------------------------------------- |
| `Authorization`     | Yes      | Your API key as a Bearer token: `Bearer max_prd_ak_...` |
| `X-Organization-Id` | Yes      | The clinic organization ID you're accessing             |

### Example

```bash theme={null}
curl -X GET "https://api.maxcare.ai/v3/patients" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"
```

## API Key Types

There are two types of API keys in the Max AI platform:

### Account API Keys

Used by the CLI for **account-level operations** such as creating apps, deploying, and managing your developer account. These are generated from the developer console and are tied to your developer identity, not a specific app.

### Data API Keys

Used by your app to **access clinic data** (patients, appointments, bills, etc.). Data API keys are bound to a specific app, and each key has its own set of scopes selected at creation time. The effective permissions of a key are the intersection of that key's scopes with the permissions granted when the app is installed.

Data API keys follow a prefixed format that indicates the environment:

| Environment | Prefix        | Example                |
| ----------- | ------------- | ---------------------- |
| Production  | `max_prd_ak_` | `max_prd_ak_SBA...01S` |
| Staging     | `max_dev_ak_` | `max_dev_ak_SBA...01S` |

## Generating a Key

1. Sign in at [app.maxcare.ai](https://app.maxcare.ai)
2. Go to **Marketplace** > Your App > **Settings**
3. Under **API Keys**, click **Generate New Key**
4. Copy the key immediately

<Warning>
  API keys are shown **only once** at creation time. Store them securely in environment variables or a secrets manager. If you lose a key, revoke it and generate a new one.
</Warning>

## Key Security Best Practices

* **Never** commit API keys to version control
* **Never** expose keys in client-side code (JavaScript bundles, mobile apps)
* Store keys in environment variables or a secrets manager (e.g., AWS Secrets Manager, Doppler, Vault)
* Rotate keys periodically and immediately if compromised
* Use separate keys for development and production

## Organization ID

The `X-Organization-Id` header tells the API which clinic's data to access. Your app can only access data from organizations (clinics) that have installed your app.

To verify your access and see which organization you're connected to:

```bash theme={null}
curl -X GET "https://api.maxcare.ai/v3/marketplace/me" \
  -H "Authorization: Bearer max_prd_ak_SBA...01S" \
  -H "X-Organization-Id: 7e2c8cfe-b7a9-4deb-986d-e7012589e72b"
```

## Error Responses

When authentication fails, the API returns structured error responses:

### 401 Unauthorized

Returned when the API key is missing, invalid, or expired.

```json theme={null}
{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Common causes:**

* Missing `Authorization` header
* Malformed Bearer token (e.g., missing `Bearer ` prefix)
* Revoked or expired API key

### 403 Forbidden

Returned when the API key is valid but lacks the required scope for the endpoint.

```json theme={null}
{
  "code": "forbidden",
  "message": "Insufficient scope. Required: read:patients",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Common causes:**

* Your app hasn't been granted the required scope
* The clinic hasn't approved the scope during app installation

See [Scopes](/guides/scopes) for the full list of permissions and which endpoints they unlock.