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

# Authentication

> Send your Perquery API key in the Authorization header of each request.

Each request to the Perquery API must include an API key. The API uses the key to find your organization and to check what the key can read.

## Send the API key

Put the key in the `Authorization` header. Write the word `ApiKey`, one space, and then the key:

```http theme={null}
Authorization: ApiKey pq_xxxxxxxxxxxx_your_secret
```

```bash curl theme={null}
curl https://perquery.ai/api/v1/sites \
  -H "Authorization: ApiKey $PERQUERY_API_KEY"
```

```python Python theme={null}
import os
import urllib.request

request = urllib.request.Request(
    "https://perquery.ai/api/v1/sites",
    headers={"Authorization": f"ApiKey {os.environ['PERQUERY_API_KEY']}"},
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode())
```

```javascript JavaScript theme={null}
const response = await fetch("https://perquery.ai/api/v1/sites", {
  headers: { Authorization: `ApiKey ${process.env.PERQUERY_API_KEY}` },
});
console.log(await response.json());
```

## Key format

A key has three parts with an underscore between them: `pq_<prefix>_<secret>`.

| Part | Description |
| - | - |
| `pq` | The fixed start of each Perquery key. |
| Prefix | 12 characters. The **Prefix** column of the **API Keys** page shows it, so you can find the key in the list. |
| Secret | The secret part. Perquery shows it one time only, when you create the key. |

Send the full key, with all three parts.

## Create a key

**1. Open the API Keys page**

In the Perquery app, open **API Keys**.

**2. Create the key**

Click **Create key**. Enter a **Name**. If necessary, set a date in **Expires (optional)**. Click **Create**.

**3. Copy the key**

Click **Copy**. Store the key in a safe place. Then click **Done**.

For all the details, read [API keys](https://docs.perquery.ai/en/account/api-keys.md).

## What a key can read

* A key is read-only. It accepts only `GET` requests.
* A key acts as the team member who created it. It reads only the data that the roles of this member allow at the time of the request.
* When the roles of the creator change, the access of the key changes too.
* When your organization does not have the API access add-on, all keys of the organization stop. The API answers `403` with `missing-entitlement`.

## When the API refuses a key

| Status | Slug | Cause |
| - | - | - |
| `401` | `unauthorized` | The header has no key, the key is not correct, the key is revoked or the key is expired. |
| `403` | `forbidden` | The request uses a method other than `GET`, or API keys cannot use this endpoint. |
| `403` | `missing-entitlement` | Your organization does not have the API access add-on. |
| `403` | `permission-denied` | The roles of the key creator do not allow this request. |

For all errors, read [Errors and limits](https://docs.perquery.ai/en/api/errors-and-limits.md).

## Keep your keys safe

> [!WARNING]
>
> A key gives access to the data of your organization. Do not put a key in browser code, in a mobile app or in a public repository.

* Keep the key in an environment variable or in a secret store, as in the examples above.
* Give each integration its own key with a clear **Name**. You can then revoke one key and keep the others.
* Set an expiry date for a key that you need only for a limited time.
* When a key is lost or shared by mistake, revoke it on the **API Keys** page at once. Then create a new key.

## Related pages

* [API introduction](https://docs.perquery.ai/en/api/introduction.md)
* [Errors and limits](https://docs.perquery.ai/en/api/errors-and-limits.md)
* [API keys](https://docs.perquery.ai/en/account/api-keys.md)


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