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

# Authentication and keys

> Organization API keys: who can create them, how they look, and how to roll and revoke them.

## Organization API keys

Every request carries an organization API key as a Bearer token.

```bash theme={null}
Authorization: Bearer pk_org_live_8kq2N4xZ0pLm3Vb7_Xr…
```

| Part | Meaning |
| - | - |
| `pk_org_live_` | Prefix. Marks an App API key, so secret scanners can find a leaked one. |
| 16 characters | Public id. Shown in Settings so you can tell keys apart. |
| 43 characters | Secret. Parlay stores only a keyed hash of the full key and can never show it again. |

A key belongs to your **organization**, not to a person's browser session. It keeps working when the person who made it signs out. It stops working when it expires, when it is revoked or deleted, or when its creator stops being an active owner or admin of the organization.

## Who can create keys

Organization **owners** and **admins** manage keys in the Parlay web app under [**Settings → API Keys**](https://app.goparlay.io/settings/api-keys), signed in with their normal Parlay account. Other members don't see the page. Key management needs a signed-in browser session on purpose: an API key can never create, rename, roll, revoke or delete keys, so a leaked key cannot make more keys.

When you create a key you choose:

| Setting | Options |
| - | - |
| Name | Up to 80 characters. Name it after the system that uses it. |
| Permissions | One or more of the [permissions](https://developers.goparlay.io/app-api/permissions.md). Grant only what the system needs. |
| Lifetime | 30, 90 or 180 days, 1 year, or **Never**. The default is 90 days. A key set to Never works until you revoke or delete it, or until its creator stops being an owner or admin. Roll it every few months as good practice. |

Keys that include `transcripts:read` ask you to accept the transcript terms first, because transcripts contain what customers said. Your acceptance (who, when and which version of the terms) is saved with the key.

## Rolling a key

**Roll** creates a replacement key with the same name and permissions. The old key keeps working for **24 hours** (or until it would have expired, if sooner), so you can deploy the new one without downtime.

**1. Roll the key in Settings**

Copy the new key. It is shown once.

**2. Deploy it**

Update your secret manager and restart or reload your service.

**3. Confirm**

Call `GET /me` with the new key. The old key stops on its own within 24 hours.

## Revoking a key

**Revoke** stops a key on its next request. Use it the moment you suspect a key was exposed, then create a new one. Requests with a revoked key return `401 unauthorized`.

## Renaming and deleting a key

**Rename** changes only the label you see in Settings. The key itself doesn't change, so nothing needs redeploying.

**Delete** stops the key on its next request, like revoke, and also removes it from your key list. Use it to clear out keys you no longer need, including old revoked or expired ones. Deleted keys still appear in your audit trail (`GET /audit-events`), so you can see what they did.

## Keeping keys safe

* **Server side only.** Never put a key in a browser, a mobile app or a public repository.
* **One key per system.** A warehouse sync and a CRM integration should each have their own key, so you can revoke one without breaking the other.
* **Least privilege.** A sync that only needs calls should not hold `contacts:read` or write permissions.
* **Watch usage.** `GET /keys/{key_id}/usage` and `GET /audit-events` show what each key did.

## Request headers

| Header | When | Purpose |
| - | - | - |
| `Authorization: Bearer <key>` | Every request | Identifies the organization and key |

## Response headers

| Header | Meaning |
| - | - |
| `X-Request-Id` | Unique id for this request. Include it when you contact support. |
| `Parlay-Version` | The API version that served the request, for example `2026-10-23`. |
| `Retry-After` | Seconds to wait, on `429` and `503` responses. |
| `Cache-Control: no-store` | API responses are never cached. |


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