---
title: API keys
description: How a firm owner creates and revokes Receptiva API keys, what each permission allows, and how to store a key safely.
sidebarTitle: API keys
section: api
order: 20
updated: 2026-10-05
---

An API key lets one of your own systems call the [REST API](/docs/api-overview) for your firm. Only the firm's owner can create or revoke keys.

## Create a key

1. Sign in to your firm's Receptiva dashboard as the owner.
2. Open **Integrations** and find **API keys**.
3. Give the key a name that says what uses it, for example "CRM sync", and choose its permissions.
4. Copy the key and store it in your system's secret storage.

The full key is shown once, when you create it. Receptiva stores only a one-way hash of it, so nobody, including Receptiva staff, can show it to you again. If you lose a key, revoke it and create a new one.

Keys start with `rcp_live_`. A firm can have up to 10 active keys. Use a separate key for each system, so you can revoke one without interrupting the others.

## Permissions

You choose one of four sets when you create a key.

| Set | What the key can do |
| --- | --- |
| Read, without transcripts | Read the account status, receptionist settings, calls with their summaries, and leads. No transcripts, no recordings and no full lead intake. |
| Read without transcripts, and update leads | Everything in Read, without transcripts, and set a lead's status to contacted, signed or rejected. No transcripts, no recordings and no full lead intake. |
| Read | Read, without transcripts, plus call transcripts, call recordings and each lead's full intake. |
| Read and update leads | Everything in Read, and set a lead's status to contacted, signed or rejected. |

Every set also lets the key read your firm's [webhook](/docs/webhooks) endpoints, deliveries and events, send a test event and resend a delivery. Keys created before webhooks were available do not have this; create a new key to use it.

Each endpoint names the permission it needs, as a scope such as `calls:read`. A request with a key that lacks it answers `403` with the code `insufficient_scope`. A key can read its own permissions at `GET /v1/account`: `api_key` there lists its name, its `scopes` and when it expires, so an integration can check what it may do before it starts.

| Scope | Allows |
| --- | --- |
| `org:read` | `GET /v1/account` |
| `receptionist:read` | `GET /v1/receptionist` |
| `calls:read` | Listing calls and reading one call |
| `calls:transcript` | Reading a call's transcript |
| `calls:recording` | Playing a call's recording and creating a recording link. Keys created before recordings were available do not have it; create a new key to use recordings. |
| `leads:read` | Listing leads |
| `leads:narrative` | Reading one lead with its full intake |
| `leads:write` | Setting a lead's status |
| `webhooks:read` | Listing your webhook endpoints, their deliveries and your firm's events. See [Webhooks](/docs/webhooks). |
| `webhooks:test` | Sending a test event to an endpoint and resending a delivery. It cannot add, change or delete an endpoint. |

Transcripts, recordings and lead intake hold what callers said about their injuries and treatment. A key in the Read set or the Read and update leads set can read them, whatever the **Full caller data for AI assistants** setting says. That setting applies only to AI assistants connected through the MCP connector, because a key sends data to a system your firm runs. If the system does not need transcripts, recordings or intake, choose Read, without transcripts, or Read without transcripts, and update leads if it writes lead statuses back.

## Revoke a key

In **Integrations**, choose **Revoke** next to the key. It stops working on its next request and cannot be turned back on.

Revoke a key when the system that used it is retired, when someone who had access to it leaves, or if it may have been exposed, for example pasted into a chat or committed to a code repository.

## Rotate a key

To replace a key without interrupting the system that uses it:

1. Create a second key with the same permissions.
2. Deploy the new key to the system, in place of the old one.
3. In **Integrations**, check that the new key's last-used time has moved, which shows the system is using it.
4. Revoke the old key.

A firm can have up to 10 active keys, so there is room for the second key while both exist. If the firm is at the limit, revoke a key nothing uses first.

## Keep keys safe

- Store keys in a secrets manager or environment variable on a server.
- Never put a key in browser or mobile code, or in a URL.
- Give each system its own key with the smallest set of permissions it needs.
- The dashboard shows when each key was last used. Revoke keys nothing uses.

## What is recorded

Receptiva records who created and who revoked each key in its audit log. Every call and lead read made with a key is recorded there too, with the key's id, the same way reads through the connector are. See [Data and privacy](/docs/data-privacy).

## Next

- [REST API overview](/docs/api-overview)
- [Keep another system in sync](/docs/sync-guide)