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

# Authentication

> How to authenticate with RxScale APIs

# Authentication

All RxScale APIs use API key authentication. Include your API key in the `X-API-Key` header with every request.

## API Key Header

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/external_pharmacy_api/health/" \
  -H "X-API-Key: your-api-key-here"
```

### Alternative Public API Headers

The Public API also accepts `X-RxScale-Authorization` as an alternative to `X-API-Key`. This is supported for backward compatibility with existing integrations.

```bash theme={null}
curl -X GET "https://api.rxscale.com/v2/public-api/health/" \
  -H "X-RxScale-Authorization: your-api-key-here"
```

You can also send the same API key as a bearer token in the `Authorization` header.

```bash theme={null}
curl -X GET "https://api.rxscale.com/v2/public-api/health/" \
  -H "Authorization: Bearer your-api-key-here"
```

<Note>
  New integrations should use `X-API-Key` unless your platform requires bearer-token
  authentication. The `X-RxScale-Authorization` and `Authorization: Bearer` headers
  are only supported on Public API endpoints.
</Note>

## API Key Types

### Pharmacy API Keys

Pharmacy API keys can be scoped to:

* **A single pharmacy** — The key can only access data for that specific pharmacy.
* **A pharmacy group** — The key can access data for any pharmacy in the group. When using a group-wide key, you must include the `pharmacy_uid` query parameter to specify which pharmacy you are acting on.

### Management API Keys

Management API keys are scoped to an **organisation**. They can access data for all entities within that organisation.

## Permissions

Each API key has a set of permissions that control which endpoints it can access. Common permissions include:

| Permission          | Description                  |
| ------------------- | ---------------------------- |
| `orders_read`       | List and view orders         |
| `orders_write`      | Update order status          |
| `stock_read`        | List SKUs and stock levels   |
| `stock_write`       | Update stock levels          |
| `prescription:read` | View prescription data       |
| `product:read`      | View product catalog         |
| `webhooks_read`     | List webhook subscriptions   |
| `webhooks_write`    | Register and manage webhooks |

## Creating API Keys

### As an Admin (Management API & Public API)

1. Log in to the **Admin Tool**
2. Navigate to **Settings** → **API Keys**
3. Click **Create API Key**
4. Enter a display name for the key
5. Select the permissions you want to grant (e.g. `order:read`, `product:read`, `prescription:read`)
6. Click **Create** — the key will be shown once. Copy and store it securely.

<Warning>
  The API key is only shown once at creation time. If you lose it, you will need to create a new one.
</Warning>

### As a Pharmacist (External Pharmacy API)

1. Log in to the **Pharmacy Tool**
2. Navigate to **Settings** → **API Keys**
3. Create a new key scoped to your pharmacy or pharmacy group
4. Select the required permissions (e.g. `orders_read`, `orders_write`, `stock_read`)

<Note>
  Pharmacy API keys can be restricted to a single pharmacy or cover an entire pharmacy group. Group-wide keys require the `pharmacy_uid` parameter on each request.
</Note>

## Error Responses

If authentication fails, you will receive one of these responses:

| Status Code | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `401`       | Missing or invalid API key                                   |
| `403`       | Valid API key but insufficient permissions for this endpoint |
| `404`       | Resource not found or not accessible with your key           |

<Warning>
  For security, RxScale returns `404 Not Found` instead of `403 Forbidden` when you try to access a resource outside your scope. This prevents resource enumeration.
</Warning>