Skip to main content

Scopes

A scope caps what a token may do. Give a token only the scopes it needs. A leaked token can then do less. The app calls a token's scopes its Access limits.

Two checks on every call​

A call succeeds when both of these hold:

  1. The access behind the token holds the privilege. For a workspace token that is the token's own grants. For a personal token it is the person's access, narrowed by the token's Permissions and Authorized organizations. A privilege such as organization.create is held at particular organizations or across the workspace.
  2. One of the token's scopes carries that privilege.

A personal token or workspace token created with no access limits carries every scope. Only the first check applies to it. A token created with any scope also carries workspace:read. The token still needs a role that holds organization.read to read organizations, and both organization.read and agent.read to read agents.

A scope never adds access. A token with fleet:write and a role that cannot create organizations still cannot create one. Each example use case names both the role and the scope it needs.

Standard roles​

Access comes from roles. Choose the role first, then the scope. A workspace has these standard roles. List roles returns them with every privilege each holds.

RoleWhat it is for
AdministratoradminAdministers the whole workspace with every privilege, its people, access and settings included.
Organization Administratororganization_adminAdministers the organizations it is granted over, their agents, people and access included, with no workspace settings.
EngineerengineerCreates and changes organizations, deploys and manages agents, ingest keys and registration tokens, and queries and reads log data, where it is granted; it cannot move an organization.
AnalystanalystQueries and reads log data and device health where it is granted, and changes nothing.
Analyst (no raw logs)analyst_no_raw_logsQueries counts, patterns and device health where it is granted, without reading raw log events, and changes nothing.
Deployment Managerdeployment_managerDeploys and manages organizations, agents, agent policy, ingest keys and registration tokens where it is granted, with no access to log data.
AuditorauditorReviews people, access, configuration and the audit log, with no access to log data, and changes nothing.
Finance Adminfinance_adminManages billing and reads usage, with read access to organizations and no access to log data.

Scopes and what each allows​

ScopeWhat it carries
workspace:readRead the workspace, its organizations and its agents.workspace.readorganization.readagent.read
events:queryQuery log events and see how much data the workspace ingests.event.queryingestion.read
events:readRead individual log events, and App Analytics data, which is stored as events.event.readanalytics.query
devices:readRead device health and state.device.read
analytics:readQuery App Analytics data, and nothing else.analytics.query
admin:readRead members, groups, the audit log and archive settings.member.readgroup.readauditlog.queryarchive.config.read
fleet:deploywriteCreate, read, change, revoke, delete and restore registration tokens, and create, reveal and replace ingest keys, secrets included. With the workspace:read every scoped token carries, it also lists the organizations these belong to.registration_token.readregistration_token.createregistration_token.revealregistration_token.revokeingest_key.createingest_key.revealingest_key.rotate
fleet:writewriteCreate, change, move, delete and restore organizations; change, move, delete and restore agents and ingest keys; and everything fleet:deploy allows.organization.createorganization.writeorganization.deleteorganization.moveagent.writeagent.deleteagent_policy.writeagent_policy.assignagent_policy.rule_writeagent_tag.attachingest_key.createingest_key.revealingest_key.rotateregistration_token.createregistration_token.readregistration_token.revealregistration_token.revoke
admin:writewriteChange workspace settings, members, groups and grants, and everything admin:read allows.workspace.writemember.readmember.managegroup.readgroup.writegrant.writeauditlog.queryarchive.config.readarchive.config.writeagent_policy.enforceagent_tag.define
admin:delegatewriteGive a role that manages other people's tokens and app registrations, and change another workspace token's grants. The token itself never creates, reads or changes a token or an app registration: those calls take a signed-in session.user_token.view_alluser_token.manage_anyworkspace_token.createworkspace_token.viewworkspace_token.manageapp_registration.createapp_registration.viewapp_registration.manage

No scope carries: finance.adminuser_token.create_ownuser_token.manage_own

fleet:deploy, fleet:write and admin:write change things or reveal secrets, and are marked "write" in the first table. fleet:deploy is the narrowest of the three, meant for deployment. It creates, reads, changes, revokes, deletes and restores registration tokens, and creates, reveals and rotates ingest keys. It cannot touch organizations, agents or people.

The second table lists the scopes of the AI and query interfaces. No call in this API needs a scope from the second table. A token that gives a role must still carry those scopes when the role's privileges fall under them.

A connected app (an OAuth token) carries a write scope only when the app asked for it and the person approving ticked it on the consent screen.

When a call is refused​

A call refused for lack of a privilege returns 403, and cause names the check that failed:

causeMeaningWhat to do
token_scopeThe token's scopes leave the privilege out. required_scope names the scope that would allow the call.Edit the token's access limits in the app, or create a token with that scope. For a connected app, reconnect and approve the scope.
no_privilegeThe access behind the token does not hold the privilege. privilege names it.Give the person, group or workspace token a role that holds it at the organization the call names. For a personal token, also check the token's own Permissions and Authorized organizations.

Other refusals carry no cause: a kind of credential the call does not take, or a change that would give away access the caller does not hold.

A wrong id looks like a missing privilege​

A call about an object the token cannot see is answered exactly like one about an object that does not exist. This stops a caller from probing for ids. A read returns 404 in both cases. A change to an organization, agent, ingest key or registration token returns 403 APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION with cause no_privilege, the same response as when the role does not allow the change there.

Response 403
{  "at_org": true,  "cause": "no_privilege",  "error": "this credential does not have the privileges to perform this action on the organization 0a9e0000-0000-4000-8000-000000000105",  "error_code": "APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION",  "privilege": "organization.write"}

To tell the two apart, read the object first. A 404 means the id is wrong or out of the token's reach. A 200 means the id is right and the role is what is missing. See Errors for every code and field.

Giving access takes more than one scope​

See the table in the next section for the scope each call needs. Calls that give or take away access have a second condition: the token must itself cover the role involved. A role's privileges fall under several scopes, and the token needs all of them.

For example, admin:write lets a token create a grant. To grant the Engineer role, the token also needs every scope that Engineer's privileges fall under. Without them the call returns 403 with cause token_scope, and required_scope names a missing scope.

A role that manages other people's API tokens and app registrations, such as Organization Administrator, also needs admin:delegate. A token with admin:delegate can give such a role, and can change another workspace token's access. It cannot create, read, rename or revoke a token or an app registration: those take a person signed in to the app. A workspace token cannot change its own access.

Setting a group's members follows the same rule, whether it adds people or removes them: the token must cover every role the group's grants give. Each example use case lists the full set of scopes for the role it gives. A token with no access limits covers every role its own access holds. Use one when the token's work is managing access.

Which scope each call needs​

Call
workspace:read
events:query
events:read
devices:read
analytics:read
admin:read
fleet:deploy
fleet:write
admin:write
admin:delegate
Read a workspaceworkspace:read
Update a workspaceadmin:write
Update onboardingfleet:write
Update the ingest policyadmin:write
List regions
List replication targetsadmin:readadmin:write
List organizationsworkspace:read
Read an organizationworkspace:read
Create an organizationfleet:write
Update an organizationfleet:write
Delete an organizationfleet:write
Restore a deleted organizationfleet:write
Check a client idfleet:write
Move an organizationfleet:write
List agentsworkspace:read
Read an agentworkspace:read
Count agentsworkspace:read
Update an agentfleet:write
Delete an agentfleet:write
Restore a deleted agentfleet:write
Move an agentfleet:write
Read the agent releaseworkspace:read
List ingest keysworkspace:read
Read an ingest keyworkspace:read
Create an ingest keyfleet:deployfleet:write
Update an ingest keyfleet:write
Delete an ingest keyfleet:write
Restore a deleted ingest keyfleet:write
Move an ingest keyfleet:write
Read an ingest key's secretfleet:deployfleet:write
Replace an ingest key's secretfleet:deployfleet:write
List registration tokensfleet:deployfleet:write
Read a registration tokenfleet:deployfleet:write
Create a registration tokenfleet:deployfleet:write
Update a registration tokenfleet:deployfleet:write
Delete a registration tokenfleet:deployfleet:write
Restore a deleted registration tokenfleet:deployfleet:write
Read a registration token's secretfleet:deployfleet:write
Revoke a registration tokenfleet:deployfleet:write
List membersadmin:readadmin:write
Remove a memberadmin:write
List invitationsadmin:readadmin:write
Invite a personadmin:write
Withdraw an invitationadmin:write
Send an invitation emailadmin:write
List groupsadmin:readadmin:write
Read a groupadmin:readadmin:write
Create a groupadmin:write
Rename a groupadmin:write
Set a group's membersadmin:write
Delete a groupadmin:write
Give a grantadmin:write
Replace a grantadmin:write
Remove a grantadmin:write
Change a grantee's grants togetheradmin:write
List rolesworkspace:read
Read your access in a workspaceworkspace:read
List audit eventsadmin:readadmin:write
Read an audit eventadmin:readadmin:write
Read credential metadata
Rotate the credential's secret
Read your profile