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

# Authentication

> How to authenticate requests and manage sandbox vs production environments

## API keys

All requests to the Pharmachain Partner API must include your API key as a
Bearer token in the `Authorization` header.

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

Generate and manage your keys from **Settings → API keys** in the
[Partner Portal](https://partners.pharmachains.ai).

<Warning>
  Treat your API key like a password. Never commit it to version control,
  never include it in frontend or mobile code. Rotate it immediately if
  you suspect it has been exposed.
</Warning>

## Environments

Pharmachain provides two environments. Use sandbox while building and testing —
no real pharmacy orders will be placed.

<CardGroup cols={2}>
  <Card title="Sandbox" icon="flask">
    `https://sandbox-api.pharmachains.ai/v1`

    Safe for development and testing. Returns realistic mock data.
    No real pharmacies or fulfilment involved.
  </Card>

  <Card title="Production" icon="circle-check">
    `https://api.pharmachains.ai/v1`

    Live environment. Requests are routed to real verified pharmacies
    and fulfilled end-to-end.
  </Card>
</CardGroup>

<Note>
  Your sandbox and production API keys are different. You'll find both
  in the Partner Portal under **Settings → API keys**.
</Note>

## Key rotation

You can generate a new key at any time without downtime.

<AccordionGroup>
  <Accordion icon="rotate" title="How to rotate your API key">
    1. In the Partner Portal, go to **Settings → API keys**.
    2. Click **Generate new key** — your existing key stays active.
    3. Update the key in your production environment variables.
    4. Confirm the new key is working.
    5. Revoke the old key.

    <Tip>
      Never delete the old key before confirming the new one is live.
      Both keys are valid simultaneously during the switchover window.
    </Tip>
  </Accordion>
</AccordionGroup>

## Scopes

Each API key can be scoped to specific permissions. When generating a key,
select only the scopes your integration requires.

| Scope              | What it allows                                |
| ------------------ | --------------------------------------------- |
| `medicines:search` | Query medicine availability across pharmacies |
| `requests:create`  | Submit new medicine fulfilment requests       |
| `requests:read`    | Read request status and timeline              |
| `requests:cancel`  | Cancel pending requests                       |
| `webhooks:manage`  | Register and manage webhook endpoints         |

## Error reference

| HTTP status | Error code            | Meaning                                             |
| ----------- | --------------------- | --------------------------------------------------- |
| `401`       | `invalid_api_key`     | Key is missing, malformed, or has been revoked      |
| `401`       | `expired_api_key`     | Key has passed its expiry date — rotate immediately |
| `403`       | `insufficient_scope`  | Key does not have permission for this action        |
| `429`       | `rate_limit_exceeded` | You've exceeded the allowed request rate            |

## Rate limits

| Environment | Requests / minute | Requests / day |
| ----------- | ----------------- | -------------- |
| Sandbox     | 60                | 5,000          |
| Production  | 300               | 100,000        |

<Note>
  If your integration requires higher production limits, contact your
  Pharmachain account manager at [support@pharmachains.ai](mailto:support@pharmachains.ai).
</Note>