API keys
Create, limit and revoke the keys your workflows, code and agents call Operate As with.
A key is how n8n, your code or an agent proves it acts for your agency. It says who is calling and what they may reach. It never holds a client's access, so a leaked key is fixed by revoking it, and your clients never reconnect.
Create a key
Open API & webhooks → Create key
You need permission to manage keys in your agency.
Name it and limit it
Name it after where it lives, such as n8n production or Booking agent, and choose how long it Works for: until you revoke it, or 30 days, 90 days or a year.
Full access reaches every client, service and tool, including ones you add later. Restricted reaches only the clients, services or tools you choose. Under Limits you can also lock the key to IP addresses and cap how fast it calls. See Limit what a key can reach.
Copy it now
The whole key, starting oa_, is shown once. Put it in n8n, your secret store or your agent's settings.
export OPERATE_AS_API_KEY="oa_..."Shown once
Operate As stores only a hash of the key, so nobody can show it again, not even us. After that the dashboard shows its first ten characters, like oa_Xk29fQ…. Lost it? Revoke it and create another.
Limit what a key can reach
Every call is checked against three lists. A list you leave empty allows everything of that kind.
| Limit | The key only works for | Example | In the create form |
|---|---|---|---|
| Clients | These clients | Miller Dental | Clients |
| Services | These services | sheets, slack | Services |
| Actions | These actions, by full name | sheets.read_rows, slack.send_message | Tools |
- Pass-through needs
<service>.request. A key with an actions list can only make pass-through calls to services whose<service>.requestis on the list, such assheets.requestorhubspot.request. - Services that share an address stay apart. Some services share one API address, such as Outlook and OneDrive, which both use Microsoft Graph. A key limited to
outlookcan't use that shared address to reach OneDrive files. A few paths do reach another service's data, such as a SharePoint site's OneNote notebooks, and those need a key that can use both services. Microsoft lists them. - Some services narrow to one resource. On plans with resource limits, a key can be limited to some spreadsheets (Sheets), calendars (Calendar) or channels (Slack). It then makes only the calls that act on one of them alone, pass-through included: reading and writing a spreadsheet's values, a calendar's events, or a channel's messages. Calls that create one, list them all, or name a second one, such as copying a tab into another spreadsheet or moving an event to another calendar, are refused. The refusal lists the calls the key can make.
- Refusals say why. A call outside the limits gets
403with adetailsuch asThis key can't use hubspot. - Limits shape what the key sees.
GET /v1/me/clientslists only reachable clients and services, so the n8n pickers and an agent'slist_clientsshow only those.
Least it needs
A key that can only read one client's sheet can't do much harm if it leaks. This matters most for AI agents, which choose for themselves what to call.
Where it works from and how fast
These are under Limits in the create form. Both are optional.
| Limit | What it does |
|---|---|
| IP allowlist | The key only works from these IP addresses or CIDR blocks, such as your n8n server's 203.0.113.7 or 10.0.0.0/8. A call from anywhere else is refused, and your webhook gets api_key.refused_address |
| Rate limit | The most calls this key can make a minute, so a workflow stuck in a loop can't use up your plan's requests per minute for your other keys. On plans that include it |
A key with no IP allowlist works from anywhere. The first time it's used from a new network, your webhook gets api_key.new_address, so you can spot a key that's been copied somewhere it shouldn't be.
Short-lived keys for agents
An AI agent can be tricked into repeating what it holds, so hand it a key that runs out. Your server makes one with its long-lived key, and gives the agent only the short one:
curl -X POST https://api.operate.as/v1/keys \
-H "Authorization: Bearer $OPERATE_AS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expiresIn": 900, "services": ["sheets"]}'| A short-lived key | |
|---|---|
| Starts with | oa_tmp_ |
| Lasts | An hour unless you set expiresIn, from 60 seconds to a day |
| Reaches | No more than the key that made it, narrowed further by clientIds, services and actions if you like |
| Works from | The same addresses as the key that made it |
| Stops | When it expires, or the key that made it is revoked or expires |
| Follows changes | Narrow the key that made it, or lock it to addresses, and its short-lived keys change too. One left reaching nothing is revoked |
Short-lived keys aren't listed or counted against your plan, and can't make keys of their own. Their calls are logged under the name of the key that made them.
One key per workflow or agent
| Why | What you get |
|---|---|
| Precise revoking | Revoking one key stops only that workflow or agent |
| Useful Last used | A key that's gone quiet, or that you forgot, stands out |
| Limits fit the job | The report reads sheets. Only the booking agent writes to the calendar |
Keep each key in its own environment variable, named after it, and give each part of your code the key it needs. The dashboard suggests a name when you create a key, such as OPERATE_AS_REPORTING_KEY. The libraries take the key you pass them, and only read OPERATE_AS_API_KEY when you pass none, so one program can use several keys at once:
reporting = OperateAs(os.environ["OPERATE_AS_REPORTING_KEY"])
bookings = OperateAs(os.environ["OPERATE_AS_BOOKINGS_KEY"])How many keys
Your plan sets how many live keys your agency can have. Revoked and expired keys don't count. See Plans and limits.
| Situation | What happens |
|---|---|
| At the allowance, creating a key | Refused until you revoke one or upgrade |
| Over the allowance, such as after a downgrade | Keys beyond the allowance answer 403 until you revoke one or upgrade |
Last used
The list shows when each key last made a call that reached a service, or Never. A key never used, or idle for months, is a good one to revoke.
Revoke a key
Choose Revoke and confirm. The next call with it gets 401 (That API key doesn't exist or was revoked.). This can't be undone, so create a new key and swap it in.
Revoking never touches your clients' connections. They stay connected, and every other key keeps working.
Never put a key in a browser
Anyone who opens your page can read a key in its JavaScript and call your clients' services as you. Call Operate As from a server, n8n or an agent you run. The same goes for mobile apps, public repos and screenshots: if a key may have been seen, revoke it.