Choose a key

Every request carries a Task API key. To create one, go to Settings > API > Task keys > New key in the app and pick its type. Only organization administrators can create a service account key. The type decides who the agent works as, what it can reach and whether it can approve tool calls.

You can limit any key to an agent list (its Agent scope), so it runs only those agents. If you aren’t sure which key to use, start with a personal key. Move the job to a service account key once it runs without you, and narrow the key’s agent list to the agents it runs.

Call your own agents from your own code

Use a personal key. It acts as you. It can run the agents you can run, narrowed to its agent list if it has one. It can read the sessions you own, and use your connected accounts and the organization’s shared connectors that the agent has access to. If the key has the tasks:approve capability, it can approve tool calls. With agents:write, it can create agents and edit any agent you can edit in the app. It can read back the instructions only of agents you created and still own.

Run automations, backends and CI

Use a service account key. An organization administrator creates it and picks an agent for it. The key acts as that agent on behalf of the organization, not as a person. It uses the connected accounts of the administrator who created it, not the organization’s shared connectors. It can run every agent in the organization, or only the agents on its agent list if it has one. It runs every session in the cloud (env_default). Its rate limit is 2,500 requests a minute, compared with 7,500 for a personal key. It can’t approve tool calls, so the agents it runs must not have any tool set to Ask (where each call waits for a person to approve it).

When it creates a session, it can name any active member of the organization as the owner, with the x-context-owner-user-id or x-context-owner-user-email header. Otherwise the administrator who created the key owns the session, and the session doesn’t appear in the app’s task lists. The key reads only the sessions it created, and a replacement key can’t read the old key’s sessions. A member named as the owner owns that session, sees it in the app and can read it with their personal keys. No service account key can read sessions you start yourself.

If that administrator is removed from the organization, the key is revoked. While that administrator is banned (suspended but not removed), every request with the key returns 401. Requests succeed again when the ban ends. Requests also return 401 if the agent the key acts as is deleted, or while that agent’s owner isn’t a member of the organization. Before an administrator leaves, replace the keys they created.

Side by side

	Personal key	Service account key
Who creates it	Any member can create one for themselves.	An organization administrator creates it.
Acts as	It acts as you.	It acts as the agent picked when the key was created, on behalf of the organization rather than a person.
Agents it can run	It runs the agents you can run (the app’s agent picker), narrowed to the key’s agent list if it has one.	It runs every agent in the organization, or only those on the key’s agent list.
Connectors	It uses your connected accounts, plus the organization’s shared connectors the agent can use.	It uses the connected accounts of the administrator who created the key.
Approvals	It approves tool calls set to Ask, when the key has tasks:approve.	It can’t approve tool calls. A session on an agent with a tool set to Ask goes idle with stop_reason.type: "requires_action" and waits, and every user.tool_confirmation returns 403 permission_error. Set those tools to Allow in the app before you start sessions with the key.
Who can read its sessions	You can, in the app and with your personal keys.	The key itself can, over the API. A session it created for a member also shows in that member’s app and is readable with their personal keys. Without a named owner, the session is hidden from the app’s task lists and owned by the administrator who created the key.
Deleting	With sessions:delete, it deletes any session you own. It deletes the files you uploaded.	With sessions:delete, it deletes only the sessions it created. It deletes only the files it uploaded.
Creating and editing agents	With agents:write, it creates agents you own and edits agents you can edit in the app.	It can’t create or edit agents. Every create or update returns 403.
Skills	With skills:write, it creates and deletes your own skills.	It reads skills, but can’t have skills:write.
Rate limit	It gets 7,500 requests a minute.	It gets 2,500 requests a minute.
Survives its creator leaving	No. It’s revoked when you’re removed from the organization.	No. It’s revoked when the administrator who created it is removed. Requests also return 401 if the agent it acts as is deleted or that agent’s owner leaves.

Rate limits apply only where your deployment enforces them.

Two planned changes affect service account keys. The key will use only the organization’s shared connectors that the agent has access to, not its creator’s connected accounts. Organization administrators will be able to read its sessions in the app.

Next, see which capabilities a key needs for each endpoint, or start the Quickstart to run your first session.