> ## 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.

# API keys

> Create, copy, rename and revoke the read-only API keys of your organization.

An API key lets another program read your Perquery data through the API. Keys are read-only and belong to your organization.

## Before you start

* Your organization needs the API access add-on. See [Add-ons](https://docs.perquery.ai/en/account/add-ons.md).
* Your role needs the **API keys** permissions. See [Roles and permissions](https://docs.perquery.ai/en/account/roles-and-permissions.md).

To open the page, click **API Keys** in the user menu.

## Create a key

**1. Open the form**

On the **API Keys** page, click **Create key**.

**2. Name the key**

Enter a **Name**. Use a name that tells where you use the key.

**3. Set an expiry (optional)**

Select a date in **Expires (optional)**. The date must be after today. Without a date, the key does not expire.

**4. Create**

Click **Create**.

**5. Copy the key**

Click **Copy**. Keep the key in a safe place, for example a password manager. Then click **Done**.

> [!WARNING]
>
> Perquery shows the full key only one time. After you click **Done**, you cannot see it again. If you lose the key, revoke it and create a new one.

## What a key can read

Each key gets these scopes. The **Scopes** column shows them.

* `metrics:read`: visibility, authority, technical analysis, content analysis, bot logs, opportunities, impact and integrations.
* `catalogue:read`: sites, prompts, personas and competitors.
* `runs:read`: visibility, technical analysis and content analysis runs.

A key acts as the member who created it. It can never read more than that member can read. These rules apply:

* If the member loses a permission, the key loses it too.
* If the member is suspended, the key stops working.
* You must hold all the permissions that the scopes cover. If you do not, Perquery refuses the new key.

## Use a key

Send the key in the `Authorization` header of each request:

```http theme={null}
Authorization: ApiKey pq_<prefix>_<secret>
```

A key can only read data. Perquery refuses requests that change data. For the details, see [Authentication](https://docs.perquery.ai/en/api/authentication.md).

## The key list

The **API Keys** page lists all keys of the organization, also the revoked keys.

| Column | Content |
| - | - |
| **Name** | The name of the key. **Revoked** marks a revoked key. |
| **Prefix** | The `<prefix>` part of the key. Use it to find a key. |
| **Scopes** | What the key can read. |
| **Created** | The date of creation. |
| **Last used** | The date of the last request. **Never** shows for an unused key. |
| **Expires** | The expiry date. **Never** shows for a key without expiry. |

## Rename a key

**1. Start the rename**

Click **Rename** (the pencil icon) in the row of the key.

**2. Save**

Enter the new name. Click **Save**.

The key value does not change.

## Revoke a key

> [!WARNING]
>
> A revoked key stops working at once. You cannot make it work again.

**1. Start the revoke**

Click **Revoke** (the trash icon) in the row of the key.

**2. Confirm**

Click **Revoke?**.

## Related pages

* [Authentication](https://docs.perquery.ai/en/api/authentication.md)
* [Add-ons](https://docs.perquery.ai/en/account/add-ons.md)


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