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

# API keys

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

![API keys page in Agent Studio](https://mintcdn.com/polyai/XrMtC1rV8-sgJgHo/images/secrets/api-keys-overview.png?fit=max\&auto=format\&n=XrMtC1rV8-sgJgHo\&q=85\&s=6274a720218a02525d85365d20600256)

API keys control access to PolyAI's external APIs – including the [Agents API](https://docs.poly.ai/api-reference/agents/introduction.md), [Conversations API](https://docs.poly.ai/api-reference/conversations/introduction.md), [Handoff API](https://docs.poly.ai/api-reference/handoff/introduction.md), and [External Events API](https://docs.poly.ai/api-reference/external-events/introduction.md), as well as the [Dialog-RSN-1 API](https://docs.poly.ai/api-reference/dialog-rsn-1/reference.md). Create and manage keys from the **API Keys** tab in the workspace top bar (**Agents / Users / Usage / API Keys / Secrets**) — a workspace-level area separate from the per-agent sidebar.

> [!NOTE]
>
> **Using Dialog-RSN-1?** Any API key from your workspace works. Dialog-RSN-1 doesn't check the key's agents or permissions, so leave the defaults as they are. Use the host that matches the Studio you created the key in: a key from [studio.poly.ai](https://studio.poly.ai) works on `wss://api.studio.poly.ai/v1/realtime`, and a key from `studio.us.poly.ai` works on `wss://api.us.poly.ai/v1/realtime`. A personal access token is refused. See [Connect](https://docs.poly.ai/api-reference/dialog-rsn-1/reference.md#connect).

> [!NOTE]
>
> API keys require the [Conversations API v3](https://docs.poly.ai/api-reference/conversations/introduction.md). 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](https://docs.poly.ai/api-reference/conversations/introduction.md) – retrieve conversation transcripts and metadata |
| **Handoff** | [Handoff API](https://docs.poly.ai/api-reference/handoff/introduction.md) – read handoff details |
| **External events** | [External Events API](https://docs.poly.ai/api-reference/external-events/introduction.md) – send events to active conversations |
| Any | [Dialog-RSN-1 API](https://docs.poly.ai/api-reference/dialog-rsn-1/reference.md) – connect to the real-time voice model. It doesn't check permissions |

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](https://mintcdn.com/polyai/mC-hBNxhbQLRsMMg/images/secrets/api-keys-configuration-button.png?fit=max\&auto=format\&n=mC-hBNxhbQLRsMMg\&q=85\&s=216937a676cea5152d4a2307498e6cf6)

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](https://mintcdn.com/polyai/SYHai-Gy-f-aeXG1/images/secrets/api-keys-metrics-configuration.png?fit=max\&auto=format\&n=SYHai-Gy-f-aeXG1\&q=85\&s=6d5c338cff9f133855ebb594cc5b4e87)

> [!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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET "https://api.us-1.platform.polyai.app/v3/ws-xxxxxxxx/PROJECT-xxx/conversations" \
  -H "x-api-key: YOUR_API_KEY"
```

For detailed endpoint documentation, see the [API reference](https://docs.poly.ai/api-reference/introduction.md).

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

> [card] [Conversations API](https://docs.poly.ai/api-reference/conversations/introduction.md)
>
> Retrieve conversation metadata and transcripts programmatically.

> [card] [Handoff API](https://docs.poly.ai/api-reference/handoff/introduction.md)
>
> Access handoff context and manage transitions.

> [card] [Agents API](https://docs.poly.ai/api-reference/agents/introduction.md)
>
> Programmatically configure agents, variants, and deployments.

> [card] [External Events API](https://docs.poly.ai/api-reference/external-events/introduction.md)
>
> Send events to active conversations.