Authentication
Generate a read-only or read-and-write API key, send it with every request, and manage it over its life: who can make writes, revoking, and plan changes.
By Operelio team · Updated November 1, 2026
On this page6
How authentication works
Every Operelio API request carries an API key that identifies your workspace. No key, or a bad key, and the request is refused. This guide is the key's whole life: making one, sending it, revoking it, and keeping it safe. If you just want to see a call work first, start with the API quickstart.
API keys are on the Pro and Agency plans.
Generating an API key
Open Integrations in the rail and choose the API keys tab. Enter a name (e.g. "Production" or "Testing") and click Generate key. The full key is shown once, on the same page. Copy it immediately and store it somewhere safe. Once you dismiss it, or 30 seconds after you copy it, you can't view it again.
By default only workspace admins can create API keys. An admin can let every member create their own keys under Settings, Team, Permissions, Creating API keys. Revoking a key is always admin-only, whichever way that setting is configured.
Under Access, choose Read only or Read and write before you click Generate key. The next section explains the difference.
API keys are 35 characters: the prefix "op_" followed by 32 random hex characters. The API keys tab's list shows the first 8 (e.g. "op_a2f99…") so you can recognize a key without having the full secret. To revoke a key, a workspace admin finds it in the list, clicks Revoke, and confirms. The key starts returning 401 immediately and you can generate a replacement.
Read only or read and write
A read-only key can read everything the API shows: trails, runs, leads, jobs and files, mappings, CRM owners, Do Not Contact and reports, and check values against the list. It can't upload, run, push or change anything. A read-and-write key can do everything the API can do. Use read only for dashboards and reports, so a leaked key can't change anything.
A key's access can't be changed later. To change it, make a new key and revoke the old one, as you would for a lost key. Keys made before read-only keys existed are read and write.
Some writes also need a key made by an admin: pausing and resuming a trail, changing a routing team, adding to or removing from your Do Not Contact list, and pushing to a CRM. Those work only while the person who made the key is still an admin of the workspace. Uploads, jobs and saved workflows need only a read-and-write key, unless the job keeps Do Not Contact rows: that is an admin's choice, so it needs an admin's key too.
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": "This API key is read only. Make a key with read and write access for this.",
"code": "read_only_key"
}One of those admin writes, sent with a key whose maker isn't an admin now, returns 403 with code admin_key_required. Reads work with any key.
Using the key
Include your API key in the Authorization header of every request, with the word Bearer in front of it:
Authorization: Bearer op_your_api_key_here
The header must start with exactly "Bearer op_". A missing header, a typo, or a revoked key all return 401 Unauthorized.
Keeping your key safe
Treat your API key like a password. A read-and-write key can act on your workspace's trails, leads, files, Do Not Contact list and CRM pushes, so anyone who holds it can do what its maker can. Do not commit it to version control, share it in chat, or include it in client-side code. Use environment variables or a secrets manager. If you think a key has been compromised, revoke it on the API keys tab right away (admins only) and generate a new one.
Related
Frequently asked questions
Who can create API keys?
By default only workspace admins can create keys. An admin can open key creation to every member under Settings, Team, Permissions, Creating API keys. Revoking a key is always admin-only, whatever that setting is. If a member needs to create keys and you'd rather not open it up for everyone, make them an admin.
Can I have multiple API keys?
Yes. Generate as many as you need on the API keys tab. The 60-requests-per-minute rate limit applies per key, so separate keys for production and testing don't compete for the same allowance. The monthly API call cap is counted per workspace, though, so extra keys don't add monthly capacity.
Can I change a key from read only to read and write?
No. A key's access is set when it is made. Make a new key with the access you need, move your integration to it, and revoke the old one.
What happens if I revoke a key?
Any requests using that key immediately return 401 Unauthorized. Generate a new key and update your integration.
What happens to my keys if I downgrade to a plan without API access?
If your workspace drops below Pro (to Free or Starter), your keys stop working. Every request returns 401, but the keys themselves stay in your account. If you upgrade back to Pro or Agency, the same keys resume working without you having to regenerate or update your integration.
Where should I store my API key?
Treat it like a password. Use environment variables in production, a secrets manager (1Password, AWS Secrets Manager, etc.) for shared use, or your CI/CD platform's encrypted secrets for automated jobs. Don't commit keys to version control or paste them into chat.
Connect Operelio to your code or your assistant
Start free and add Operelio to Claude or ChatGPT today. The API and webhooks come with Pro.