API scopes

Synopsis

Each access token carries named scopes. An API request fails when the token lacks the required scope. Some scope groups use read, write, and admin levels. A higher level includes every lower level in the same group.

Example with output

Copy <WORKSPACE_ID> from agentsfleet workspace list. Replace the fake token with a tenant API key from Settings → API Keys.

curl -s 'https://api.agentsfleet.net/v1/workspaces/<WORKSPACE_ID>/fleets' -H 'Authorization: Bearer af_test_00000000'

<varies>

A valid key without fleet:read returns this scope error. The fake token above fails authentication instead.

{"title":"Insufficient scope","error_code":"UZ-AUTH-022","detail":"Missing required scope: fleet:read"}

Options

Scope	Effect	Included by
`fleet:read`	Reads fleets, events, and memory.	`fleet:write`, `fleet:admin`
`fleet:write`	Creates, updates, and messages fleets. Also reads and writes your own private drafts.	`fleet:admin`
`fleet:admin`	Deletes fleets.	None
`secret:read`	Lists secret names and metadata.	`secret:write`
`secret:write`	Creates, rotates, and deletes secrets. Deleting a secret named for a connector also needs `connector:write`.	None
`apikey:read`	Lists tenant API keys.	`apikey:write`, `apikey:admin`
`apikey:write`	Creates and rotates tenant API keys.	`apikey:admin`
`apikey:admin`	Revokes tenant API keys.	None
`grant:read`	Lists integration grants.	`grant:write`
`grant:write`	Revokes integration grants.	None
`connector:read`	Reads connector state.	`connector:write`
`connector:write`	Starts a connector setup flow and disconnects a connector, including by deleting its secret.	None
`billing:read`	Reads the tenant balance and charges.	None
`workspace:admin`	Creates and lists workspaces.	None
`library:write`	Publishes a reviewed draft as an account-owned library entry or revision, and removes an entry your account owns.	None
`platform-library:write`	Stages a reviewed draft as a platform library entry, and edits, publishes, withdraws, or deletes platform entries.	None
`approval:read`	Reads pending approvals.	`approval:resolve`
`approval:resolve`	Approves or denies a request.	None

agentsfleet approvals uses these scopes. Listing needs approval:read; approving or denying needs approval:resolve. Operator tokens may carry runner:*, platform-key:*, platform-library:*, model:*, or workspace:any. Tenant integrations do not need these scopes.

Errors

UZ-AUTH-022: Insufficient scope

The token lacks the scope named in detail. Create a new key with that scope, then retry the request. Do not add unrelated scopes. A narrower key limits the effect of a leaked key.

Overview

Health

Authentication

API keys

Users

Account management

Model provider credentials

Balance and usage

Account models

Runner administration

Runner API

Model catalog

Workspaces

Private setup chats

Workspace preferences

Secrets

Connectors

Approvals

Fleets

Fleet library

Fleet messages

Fleet memories

Fleet schedules

Fleet events

Integration grants

Webhooks

Platform administration

Synopsis

Example with output

Options

Errors

UZ-AUTH-022: Insufficient scope

​Synopsis

​Example with output

​Options

​Errors

​UZ-AUTH-022: Insufficient scope

​Related pages

Synopsis

Example with output

Options

Errors

UZ-AUTH-022: Insufficient scope

Related pages