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

# External API Authentication

> Authenticate ChainPatrol External API requests with an X-API-KEY header, create an API key from your dashboard, and choose read-only or read & write access.

We use **API keys** to authenticate requests. Organization owners and admins can
create one from **Developer › API Keys** in the
[ChainPatrol dashboard](https://app.chainpatrol.io/admin). See
[Get Your API Key](https://chainpatrol.com/docs/general/api-key.md) for a walkthrough.

## How to authenticate a request

To authenticate a request, you need to include a `X-API-KEY` header
with the value of your API key in your request:

```bash theme={null}
'X-API-KEY': '<your api key>'
```

## Key permissions

Every API key has one of two permissions, chosen when you create it:

| Permission | What the key can do |
| - | - |
| **Read only** (default) | Query and export data |
| **Read & write** | Everything a read-only key can, plus endpoints that change data |

Submitting reports needs a **Read & write** key. So does every other endpoint that
creates or changes data, such as [Create Report](https://chainpatrol.com/docs/external-api/report-create.md),
[Asset Submit](https://chainpatrol.com/docs/external-api/asset-submit.md), [Dispute Create](https://chainpatrol.com/docs/external-api/dispute-create.md),
and adding, updating or removing [organization assets](https://chainpatrol.com/docs/external-api/organization-assets-add.md)
and [asset groups](https://chainpatrol.com/docs/external-api/organization-asset-groups-create.md).

Calling one of these with a read-only key returns `403 Forbidden` with a message like:

```text theme={null}
"reportCreate" changes data, and this API key is read-only. Create an API key with read & write access to make changes.
```

A key's permission can't be changed after it is created. To get write access, create a
new key with **Read & write** selected, switch your integration to it, then revoke the
old key.

> [!NOTE]
>
> Integration organizations can only create read-only keys. If your organization needs
> write access, email [support@chainpatrol.io](mailto:support@chainpatrol.io).


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