# 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](https://sparklogs.com/docs/api/use-cases.md) 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](https://sparklogs.com/docs/api/reference/roles.md) returns them with every privilege each holds.

| Role | Id | What it is for |
| - | - | - |
| Administrator | `admin` | Administers the whole workspace with every privilege, its people, access and settings included. |
| Organization Administrator | `organization_admin` | Administers the organizations it is granted over, their agents, people and access included, with no workspace settings. |
| Engineer | `engineer` | Creates 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. |
| Analyst | `analyst` | Queries and reads log data and device health where it is granted, and changes nothing. |
| Analyst (no raw logs) | `analyst_no_raw_logs` | Queries counts, patterns and device health where it is granted, without reading raw log events, and changes nothing. |
| Deployment Manager | `deployment_manager` | Deploys and manages organizations, agents, agent policy, ingest keys and registration tokens where it is granted, with no access to log data. |
| Auditor | `auditor` | Reviews people, access, configuration and the audit log, with no access to log data, and changes nothing. |
| Finance Admin | `finance_admin` | Manages billing and reads usage, with read access to organizations and no access to log data. |

- `admin`: `workspace.read`, `workspace.write`, `member.read`, `member.manage`, `group.read`, `group.write`, `grant.write`, `auditlog.query`, `organization.read`, `organization.create`, `organization.write`, `organization.move`, `organization.delete`, `agent.read`, `agent.write`, `agent.delete`, `agent_policy.write`, `agent_policy.assign`, `agent_policy.rule_write`, `agent_policy.enforce`, `agent_tag.define`, `agent_tag.attach`, `ingest_key.create`, `ingest_key.reveal`, `ingest_key.rotate`, `registration_token.create`, `registration_token.read`, `registration_token.reveal`, `registration_token.revoke`, `archive.config.read`, `archive.config.write`, `event.query`, `device.read`, `event.read`, `analytics.query`, `ingestion.read`, `finance.admin`, `user_token.create_own`, `user_token.manage_own`, `user_token.view_all`, `user_token.manage_any`, `workspace_token.create`, `workspace_token.view`, `workspace_token.manage`, `app_registration.create`, `app_registration.view`, `app_registration.manage`
- `organization_admin`: `workspace.read`, `member.read`, `member.manage`, `group.read`, `group.write`, `grant.write`, `auditlog.query`, `organization.read`, `organization.create`, `organization.write`, `organization.move`, `organization.delete`, `agent.read`, `agent.write`, `agent.delete`, `agent_policy.write`, `agent_policy.assign`, `agent_policy.rule_write`, `agent_tag.attach`, `ingest_key.create`, `ingest_key.reveal`, `ingest_key.rotate`, `registration_token.create`, `registration_token.read`, `registration_token.reveal`, `registration_token.revoke`, `archive.config.read`, `archive.config.write`, `event.query`, `device.read`, `event.read`, `analytics.query`, `ingestion.read`, `user_token.create_own`, `user_token.manage_own`, `user_token.view_all`, `user_token.manage_any`, `workspace_token.create`, `workspace_token.view`, `workspace_token.manage`
- `engineer`: `workspace.read`, `organization.read`, `organization.create`, `organization.write`, `organization.delete`, `agent.read`, `agent.write`, `agent.delete`, `ingest_key.create`, `ingest_key.reveal`, `ingest_key.rotate`, `registration_token.create`, `registration_token.read`, `registration_token.reveal`, `registration_token.revoke`, `archive.config.read`, `archive.config.write`, `event.query`, `device.read`, `event.read`, `analytics.query`, `ingestion.read`, `user_token.create_own`, `user_token.manage_own`
- `analyst`: `workspace.read`, `organization.read`, `agent.read`, `archive.config.read`, `event.query`, `device.read`, `event.read`, `analytics.query`, `ingestion.read`, `user_token.create_own`, `user_token.manage_own`
- `analyst_no_raw_logs`: `workspace.read`, `organization.read`, `agent.read`, `archive.config.read`, `event.query`, `device.read`, `ingestion.read`, `user_token.create_own`, `user_token.manage_own`
- `deployment_manager`: `workspace.read`, `organization.read`, `organization.create`, `organization.write`, `organization.delete`, `agent.read`, `agent.write`, `agent.delete`, `agent_policy.write`, `agent_policy.assign`, `agent_policy.rule_write`, `agent_tag.attach`, `ingest_key.create`, `ingest_key.reveal`, `ingest_key.rotate`, `registration_token.create`, `registration_token.read`, `registration_token.reveal`, `registration_token.revoke`, `user_token.create_own`, `user_token.manage_own`
- `auditor`: `workspace.read`, `member.read`, `group.read`, `auditlog.query`, `organization.read`, `agent.read`, `registration_token.read`, `archive.config.read`, `ingestion.read`, `user_token.create_own`, `user_token.manage_own`, `user_token.view_all`, `workspace_token.view`, `app_registration.view`
- `finance_admin`: `workspace.read`, `organization.read`, `ingestion.read`, `finance.admin`, `user_token.create_own`, `user_token.manage_own`

## Scopes and what each allows

| Scope | What it carries |
| - | - |
| `workspace:read` | Read the workspace, its organizations and its agents. `workspace.read`, `organization.read`, `agent.read` |
| `events:query` | Query log events and see how much data the workspace ingests. `event.query`, `ingestion.read` |
| `events:read` | Read individual log events, and App Analytics data, which is stored as events. `event.read`, `analytics.query` |
| `devices:read` | Read device health and state. `device.read` |
| `analytics:read` | Query App Analytics data, and nothing else. `analytics.query` |
| `admin:read` | Read members, groups, the audit log and archive settings. `member.read`, `group.read`, `auditlog.query`, `archive.config.read` |
| `fleet:deploy` (write) | Create, 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.read`, `registration_token.create`, `registration_token.reveal`, `registration_token.revoke`, `ingest_key.create`, `ingest_key.reveal`, `ingest_key.rotate` |
| `fleet:write` (write) | Create, change, move, delete and restore organizations; change, move, delete and restore agents and ingest keys; and everything `fleet:deploy` allows. `organization.create`, `organization.write`, `organization.delete`, `organization.move`, `agent.write`, `agent.delete`, `agent_policy.write`, `agent_policy.assign`, `agent_policy.rule_write`, `agent_tag.attach`, `ingest_key.create`, `ingest_key.reveal`, `ingest_key.rotate`, `registration_token.create`, `registration_token.read`, `registration_token.reveal`, `registration_token.revoke` |
| `admin:write` (write) | Change workspace settings, members, groups and grants, and everything `admin:read` allows. `workspace.write`, `member.read`, `member.manage`, `group.read`, `group.write`, `grant.write`, `auditlog.query`, `archive.config.read`, `archive.config.write`, `agent_policy.enforce`, `agent_tag.define` |
| `admin:delegate` (write) | Give 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_all`, `user_token.manage_any`, `workspace_token.create`, `workspace_token.view`, `workspace_token.manage`, `app_registration.create`, `app_registration.view`, `app_registration.manage` |

No scope carries: `finance.admin`, `user_token.create_own`, `user_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:

| `cause` | Meaning | What to do |
| - | - | - |
| `token_scope` | The 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_privilege` | The 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)

```json
{
  "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](https://sparklogs.com/docs/api/errors.md) for every code and field.

## Giving access takes more than one scope

See the [table in the next section](#which-scope-each-call-needs) 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](https://sparklogs.com/docs/api/use-cases.md) 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` |
| - | - | - | - | - | - | - | - | - | - | - |
| **Workspaces** | | | | | | | | | | |
| [Read a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#read-workspace) | `workspace:read` | | | | | | | | | |
| [Update a workspace](https://sparklogs.com/docs/api/reference/workspaces.md#update-workspace) | | | | | | | | | `admin:write` | |
| [Update onboarding](https://sparklogs.com/docs/api/reference/workspaces.md#update-onboarding) | | | | | | | | `fleet:write` | | |
| [Update the ingest policy](https://sparklogs.com/docs/api/reference/workspaces.md#update-ingest-policy) | | | | | | | | | `admin:write` | |
| **Regions** | | | | | | | | | | |
| [List regions](https://sparklogs.com/docs/api/reference/regions.md#list-regions) | | | | | | | | | | |
| **Replication targets** | | | | | | | | | | |
| [List replication targets](https://sparklogs.com/docs/api/reference/replication-targets.md#list-replication-targets) | | | | | | `admin:read` | | | `admin:write` | |
| **Organizations** | | | | | | | | | | |
| [List organizations](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations) | `workspace:read` | | | | | | | | | |
| [Read an organization](https://sparklogs.com/docs/api/reference/organizations.md#read-organization) | `workspace:read` | | | | | | | | | |
| [Create an organization](https://sparklogs.com/docs/api/reference/organizations.md#create-organization) | | | | | | | | `fleet:write` | | |
| [Update an organization](https://sparklogs.com/docs/api/reference/organizations.md#update-organization) | | | | | | | | `fleet:write` | | |
| [Delete an organization](https://sparklogs.com/docs/api/reference/organizations.md#delete-organization) | | | | | | | | `fleet:write` | | |
| [Restore a deleted organization](https://sparklogs.com/docs/api/reference/organizations.md#restore-organization) | | | | | | | | `fleet:write` | | |
| [Check a client id](https://sparklogs.com/docs/api/reference/organizations.md#check-client-id) | | | | | | | | `fleet:write` | | |
| [Move an organization](https://sparklogs.com/docs/api/reference/organizations.md#move-organization) | | | | | | | | `fleet:write` | | |
| **Agents** | | | | | | | | | | |
| [List agents](https://sparklogs.com/docs/api/reference/agents.md#list-agents) | `workspace:read` | | | | | | | | | |
| [Read an agent](https://sparklogs.com/docs/api/reference/agents.md#read-agent) | `workspace:read` | | | | | | | | | |
| [Count agents](https://sparklogs.com/docs/api/reference/agents.md#read-agent-summary) | `workspace:read` | | | | | | | | | |
| [Update an agent](https://sparklogs.com/docs/api/reference/agents.md#update-agent) | | | | | | | | `fleet:write` | | |
| [Delete an agent](https://sparklogs.com/docs/api/reference/agents.md#delete-agent) | | | | | | | | `fleet:write` | | |
| [Restore a deleted agent](https://sparklogs.com/docs/api/reference/agents.md#restore-agent) | | | | | | | | `fleet:write` | | |
| [Move an agent](https://sparklogs.com/docs/api/reference/agents.md#move-agent) | | | | | | | | `fleet:write` | | |
| **Agent releases** | | | | | | | | | | |
| [Read the agent release](https://sparklogs.com/docs/api/reference/agent-releases.md#read-agent-release) | `workspace:read` | | | | | | | | | |
| **Ingest keys** | | | | | | | | | | |
| [List ingest keys](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-ingest-keys) | `workspace:read` | | | | | | | | | |
| [Read an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#read-ingest-key) | `workspace:read` | | | | | | | | | |
| [Create an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#create-ingest-key) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Update an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#update-ingest-key) | | | | | | | | `fleet:write` | | |
| [Delete an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#delete-ingest-key) | | | | | | | | `fleet:write` | | |
| [Restore a deleted ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#restore-ingest-key) | | | | | | | | `fleet:write` | | |
| [Move an ingest key](https://sparklogs.com/docs/api/reference/ingest-keys.md#move-ingest-key) | | | | | | | | `fleet:write` | | |
| [Read an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#reveal-ingest-key) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Replace an ingest key's secret](https://sparklogs.com/docs/api/reference/ingest-keys.md#rotate-ingest-key) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| **Registration tokens** | | | | | | | | | | |
| [List registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md#list-registration-tokens) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Read a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#read-registration-token) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Create a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#create-registration-token) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Update a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#update-registration-token) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Delete a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#delete-registration-token) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Restore a deleted registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#restore-registration-token) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Read a registration token's secret](https://sparklogs.com/docs/api/reference/registration-tokens.md#reveal-registration-token) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| [Revoke a registration token](https://sparklogs.com/docs/api/reference/registration-tokens.md#revoke-registration-token) | | | | | | | `fleet:deploy` | `fleet:write` | | |
| **Members** | | | | | | | | | | |
| [List members](https://sparklogs.com/docs/api/reference/members.md#list-members) | | | | | | `admin:read` | | | `admin:write` | |
| [Remove a member](https://sparklogs.com/docs/api/reference/members.md#delete-member) | | | | | | | | | `admin:write` | |
| **Invitations** | | | | | | | | | | |
| [List invitations](https://sparklogs.com/docs/api/reference/invitations.md#list-invitations) | | | | | | `admin:read` | | | `admin:write` | |
| [Invite a person](https://sparklogs.com/docs/api/reference/invitations.md#create-invitation) | | | | | | | | | `admin:write` | |
| [Withdraw an invitation](https://sparklogs.com/docs/api/reference/invitations.md#delete-invitation) | | | | | | | | | `admin:write` | |
| [Send an invitation email](https://sparklogs.com/docs/api/reference/invitations.md#send-invitation) | | | | | | | | | `admin:write` | |
| **Groups** | | | | | | | | | | |
| [List groups](https://sparklogs.com/docs/api/reference/groups.md#list-groups) | | | | | | `admin:read` | | | `admin:write` | |
| [Read a group](https://sparklogs.com/docs/api/reference/groups.md#read-group) | | | | | | `admin:read` | | | `admin:write` | |
| [Create a group](https://sparklogs.com/docs/api/reference/groups.md#create-group) | | | | | | | | | `admin:write` | |
| [Rename a group](https://sparklogs.com/docs/api/reference/groups.md#update-group) | | | | | | | | | `admin:write` | |
| [Set a group's members](https://sparklogs.com/docs/api/reference/groups.md#update-group-members) | | | | | | | | | `admin:write` | |
| [Delete a group](https://sparklogs.com/docs/api/reference/groups.md#delete-group) | | | | | | | | | `admin:write` | |
| **Grants** | | | | | | | | | | |
| [Give a grant](https://sparklogs.com/docs/api/reference/grants.md#create-grant) | | | | | | | | | `admin:write` | |
| [Replace a grant](https://sparklogs.com/docs/api/reference/grants.md#update-grant) | | | | | | | | | `admin:write` | |
| [Remove a grant](https://sparklogs.com/docs/api/reference/grants.md#delete-grant) | | | | | | | | | `admin:write` | |
| [Change a grantee's grants together](https://sparklogs.com/docs/api/reference/grants.md#change-grants) | | | | | | | | | `admin:write` | |
| **Roles** | | | | | | | | | | |
| [List roles](https://sparklogs.com/docs/api/reference/roles.md#list-roles) | `workspace:read` | | | | | | | | | |
| **Access** | | | | | | | | | | |
| [Read your access in a workspace](https://sparklogs.com/docs/api/reference/access.md#read-access) | `workspace:read` | | | | | | | | | |
| **Audit events** | | | | | | | | | | |
| [List audit events](https://sparklogs.com/docs/api/reference/audit-events.md#list-audit-events) | | | | | | `admin:read` | | | `admin:write` | |
| [Read an audit event](https://sparklogs.com/docs/api/reference/audit-events.md#read-audit-event) | | | | | | `admin:read` | | | `admin:write` | |
| **Credential** | | | | | | | | | | |
| [Read credential metadata](https://sparklogs.com/docs/api/reference/credential.md#read-credential) | | | | | | | | | | |
| [Rotate the credential's secret](https://sparklogs.com/docs/api/reference/credential.md#rotate-credential) | | | | | | | | | | |
| **Users** | | | | | | | | | | |
| [Read your profile](https://sparklogs.com/docs/api/reference/users.md#read-user) | | | | | | | | | | |

---

Source: <https://sparklogs.com/docs/api/scopes>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
