> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# API keys

> Create and manage API keys for accessing PolyAI's external APIs.

![API keys page in Agent Studio](/_fern-files/_img/06e8d40315eebc3ab4db39742db07b6711f248e3fa3f4ed60886b00cb05b68e8.webp)

API keys control access to PolyAI's external APIs – including the [Agents API](/api-reference/build-deploy/agents-api/overview), [Conversations API](/api-reference/legacy/conversations-api-v-3-legacy/overview), [Handoff API](/api-reference/runtime-data/handoff-api/overview), and [External Events API](/api-reference/runtime-data/external-events-api/overview). Create and manage keys from the **API Keys** page in Agent Studio.

> **Note**
>
> API keys require the [Conversations API v3](/api-reference/legacy/conversations-api-v-3-legacy/overview). If you are using v1, contact your PolyAI representative to migrate to v3 first.

## Creating an API key

1. Go to the **API Keys** tab on the workspace homepage in Agent Studio
2. Select **API key**
3. Configure the key:
   * **Name** – a label to identify this key
   * **Agents** – choose "All agents" or select specific agents (this cannot be changed after creation)
   * **Permissions** – select which APIs the key can access:

| Permission             | Grants access to                                                                                                                  |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Conversations data** | [Conversations API](/api-reference/legacy/conversations-api-v-3-legacy/overview) – retrieve conversation transcripts and metadata |
| **Handoff**            | [Handoff API](/api-reference/runtime-data/handoff-api/overview) – read handoff details                                            |
| **External events**    | [External Events API](/api-reference/runtime-data/external-events-api/overview) – send events to active conversations             |

4. Select **Create** to generate the key

> **Warning**
>
> Copy your API key immediately after creation. The full key value is only shown once.

## Viewing and managing keys

Your API keys appear on the **API Keys** page. Each entry shows:

* Key name and scope (which agents it covers)
* Expiry date
* A masked key value with a copy button
* Edit and delete options

Keys are independent – modifying or deleting one does not affect others.

## Configuring metrics

Metrics control what data appears in API responses. Configure them separately from API keys:

1. Select **Configuration** at the top of the **API Keys** page

![Configuration button on the API Keys page](/_fern-files/_img/9b482d0785273f3e9ae8d68670f39267eef4516ac1729eb1b7988f82625e9c6b.webp)

2. Enable the metrics you want available in API responses:
   * Response metrics (e.g., `CALL_IN_PROGRESS`, `CALL_COMPLETED`, `HANDOFF_REASON`, `HANDOFF_TO`)
   * Conversation transcript access

![Metrics configuration panel showing response metrics and conversation transcript options](/_fern-files/_img/10b6d7e6bcf76dc467dba1bd841653f0c9e1e0758461de9ee9a76cbeafaaee1a.webp)

> **Note**
>
> Metrics are configured at the **project level**, not per key. For data to appear in an API response, both conditions must be met: the API key must have the relevant permission **and** the project must have the metric enabled.

## Using your API key

Include the API key in the `x-api-key` header of your requests:

```bash
curl -X GET "https://api.poly.ai/v3/conversations" \
  -H "x-api-key: YOUR_API_KEY"
```

For detailed endpoint documentation, see the [API reference](/api-reference/api-reference/overview).

## Key lifecycle

* Keys have an **expiry date** set at creation time
* Expired keys stop working immediately
* You can delete keys at any time from the API Keys page
* There is no limit to the number of keys you can create

## Best practices

* Create separate keys for different integrations (e.g., one for your CRM, one for analytics)
* Use the most restrictive permissions needed for each integration
* Rotate keys periodically by creating a new key before deleting the old one
* Monitor key usage through your API response logs

## Related pages

#### [Conversations API](/api-reference/legacy/conversations-api-v-3-legacy/overview)

Retrieve conversation metadata and transcripts programmatically.

#### [Handoff API](/api-reference/runtime-data/handoff-api/overview)

Access handoff context and manage transitions.

#### [Agents API](/api-reference/build-deploy/agents-api/overview)

Programmatically configure agents, variants, and deployments.

#### [External Events API](/api-reference/runtime-data/external-events-api/overview)

Send events to active conversations.