Authentication

Requests authenticate with an API key sent in the x-api-key header.

curl https://api.recepta.ai/api/v1/api/calls \
  -H "x-api-key: rcp_your_key_here"

Keys are prefixed rcp_. Each key belongs to one workspace, and every request it makes is scoped to that workspace.

Dashboard sessions authenticate with a bearer token instead. Endpoints in this reference accept either, but use an API key for anything server-to-server — it’s scoped, revocable, and doesn’t expire with a login session.

Creating a key

Open API keys

In the dashboard, go to API keys.

Name it for its use

“Zapier booking sync”, not “key 2”. You’ll thank yourself when deciding what’s safe to revoke.

Grant only what it needs

Pick the narrowest set of permissions that does the job. See the table below.

Copy it now

The full key is shown once. Afterwards only a preview — first characters and last four — is visible.

Keys are stored hashed. If you lose one, it can’t be recovered — revoke it and create a new one.

Permissions

Permission	Grants
`calls:read`	List, search, and retrieve calls
`calls:create`	Create web, phone, and outbound calls
`calls:trigger`	Trigger calls
`calls:transcript`	Retrieve call transcripts
`calls:recording`	Retrieve call recordings
`calls:delete`	Delete calls
`analytics:read`	Read call analytics
`contacts:read`	List and retrieve contacts
`contacts:create`	Create contacts
`contacts:update`	Update contacts
`contacts:delete`	Delete contacts
`sms:read`	Read SMS conversations and messages
`sms:send`	Send SMS
`*`	Everything — avoid outside trusted internal use

Transcript and recording access are separate from calls:read on purpose. An analytics integration can read call metadata without ever touching what your customers actually said.

A request with a valid key but insufficient permission returns 403.

Expiry

Keys can be given an expiry date. Worth using for anything temporary — a contractor’s integration, a one-off migration — so access ends on its own rather than relying on someone remembering.

Keeping keys safe

Do

Store in environment variables or a secret manager. One key per integration. Rotate on any suspicion, and when someone with access leaves.

Don't

Commit keys to source control. Put them in frontend JavaScript or a mobile app. Share one key across several systems — you then can’t revoke one without breaking the rest.

Never call this API directly from a browser or mobile app. Anything shipped to a user’s device is readable by that user. Proxy through your own backend.

Revoking

Deactivate a key from API keys; it stops working immediately. Keys are independent of the user who created them, so removing a team member does not revoke keys they made — rotate those separately. See Team & roles.

Scoping to a location

Add x-location-id to restrict a request to one location:

curl https://api.recepta.ai/api/v1/api/calls \
  -H "x-api-key: $RECEPTA_API_KEY" \
  -H "x-location-id: LOCATION_ID"

Overview

Endpoints

Automation

Creating a key

Permissions

Expiry

Keeping keys safe

Do

Don't

Revoking

Scoping to a location

​Creating a key

​Permissions

​Expiry

​Keeping keys safe

Do

Don't

​Revoking

​Scoping to a location

Creating a key

Permissions

Expiry

Keeping keys safe

Revoking

Scoping to a location