API key roles
This page is for platform operators who hand out to and to the systems that manage a project.
Every has one of three roles. The role decides which of the project’s APIs the key can use.
| Role | Calls the project’s tools | Manages the project (gateways, servers, secrets, users) | Use it for |
|---|---|---|---|
| Tool executor | Yes | No | A headless agent. Give each agent its own. |
| Platform manager | No | Yes | A pipeline that configures the project. |
| Platform admin | Yes | Yes | A system that needs both. Use it sparingly. |
No role reaches the organization’s APIs, such as organization hooks and plugins.
A key created before key roles existed is a platform admin and keeps the access it always had.
Give each agent its own key
A executor key can:
- Call tools through every gateway in its that accepts , including gateways created after the key.
- List and read the ’s tools, authorize a for an end , and call it through the tools API.
Every other API refuses it with 403 Forbidden, so an agent can’t read, change, or delete the around it. It can’t reach another project’s gateways either.
Name each tool executor key after the agent that uses it. Other admins of the see the name in the list, and two executor keys in a project can’t share a name, ignoring case. The name of a deleted key can be used again.
Create a key with a role
In the dashboard, you choose a key’s role by turning on what it can do.
| Call tools | Configure the project | Role | Shown in the key list as |
|---|---|---|---|
| On | Off | Tool executor | Call tools |
| Off | On | Platform manager | Configure |
| On | On | Platform admin | Full access |
Open the API Keys page
In the Arcade Dashboard, go to the and open .
Start a new key
Click Create , then enter a name. For a tool executor key, name it after the that uses it, such as support-agent.
Choose its access
Under Access, turn on Call , Configure the , or both. A new key starts with only Configure the project on. The dashboard marks a key with both on as Full access. A key’s access can’t be changed after it’s created.
Copy the key
Click Create key and copy the key. It’s shown only once.
The list shows each key’s access and status.
Over the API, send role as tool_executor, platform_manager, or platform_admin when you create a key, and its name as label. A key created without a role is a platform manager, which can’t call .
Deactivate and reactivate a key
Deactivate a key to stop one agent without affecting the others. On the page, click the power icon next to the key and confirm. Its status changes to Deactivated.
Calls with a deactivated key are refused, usually within seconds and always within five minutes, even from an that was calling just before. The key keeps its secret, so reactivating it from the same icon lets the agent work again without a new key.
Only a Admin or Org Admin can deactivate or reactivate a key. Over the API, send {"enabled": false} or {"enabled": true} to update the key.
What a refused call looks like
| Situation | Response |
|---|---|
| A tool executor key calls an API that manages the project | 403 Forbidden |
| A platform manager key calls or authorizes a tool | 403 Forbidden |
| A deactivated key calls anything | 401 Unauthorized |
| Arcade can’t check the key’s role, for example during an outage | 503 Service Unavailable |
A 503 is temporary: retry the call. Arcade refuses the call rather than guess the key’s role.
Last updated on