An API key lets one of your own systems call the REST API for your firm. Only the firm's owner can create or revoke keys.
Create a key#
- Sign in to your firm's Receptiva dashboard as the owner.
- Open Integrations and find API keys.
- Give the key a name that says what uses it, for example "CRM sync", and choose its permissions.
- 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 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. |
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:
- Create a second key with the same permissions.
- Deploy the new key to the system, in place of the old one.
- In Integrations, check that the new key's last-used time has moved, which shows the system is using it.
- 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.