Scopes

In the same way that users in DX have certain permissions, tokens have certain scopes. You can use a Personal Access Token or an Organization Token to authorize your requests to the DX API. The scopes on your token determine which endpoints you are able to call in your request.

Organization tokens can only be created by Workspace Admins and can be provisioned with all scopes.

Personal Access Tokens, on the other hand, can be created by any user and are scoped based on their creator’s role — only the scopes permitted by that role are available when creating the token.

Most roles in DX map to a specific set of scopes. Users with multiple roles can create Personal Access Tokens with the union of scopes across all their roles. However, there is a set of roles that do not map to a set of scopes.

If a user’s only role is one of the below, they can only assign the default “All Users” scopes to their Personal Access Tokens. If the user holds other roles, they can also assign the scopes associated with those roles.

The following roles do not map to a specific set of scopes:

Contributor
Data Integrator
Finance Manager
Interviewer
Priviledged User
Scorecard Admin
Snapshot Analyst
Snapshot Observer
Team Lead

Below is the full set of scopes available, as well as how they map to each role and what endpoints they provide access to.

Scope availability per user role

Note: Scope availability is contingent on which product features are enabled for your account. For example, scorecard, catalog, and workflow scopes are only available to Fabric customers.

Scope	All users	Snapshot Admin	Database Admin	Self-Service Admin	Workspace Admin
accountSettings:read					✓
apiKeys:read					✓
auditLogs:read					✓
catalog:read	✓	✓	✓	✓	✓
catalog:write:entities			✓		✓
platformx:manage		✓			✓
scorecards:read	✓	✓	✓	✓	✓
snapshots:admin		✓			✓
snapshots:read	✓	✓	✓	✓	✓
teams:manage					✓
userGroups:read		✓	✓		✓
userGroups:write		✓	✓		✓
users:read					✓
users:write		✓			✓
workflowRuns:trigger	✓	✓	✓	✓	✓
workflowRuns:writeEvents				✓	✓
workflows:read	✓	✓	✓	✓	✓

Data Studio and Data Cloud scopes for Personal Access Tokens

Workspace Admins and Snapshot Admins control who can access Data Studio in Admin > Access & Visibility:

Dropdown where admin can set Data Studio access

Only users whose role matches the selected dropdown option will be able to add the following scopes to their Personal Access Token:

datacloud:query
scorecards:write
studio:reports:read
studio:reports:write

The options are:

Everyone — All users gain access to these scopes.
Admins and privileged users — Users with the following roles gain access:
- Snapshot Admin
- Workspace Admin
- Scorecard Admin
- Database Admin
- Privileged User
Admins, privileged users, and team leads — Users with the following roles gain access:
- Snapshot Admin
- Workspace Admin
- Scorecard Admin
- Database Admin
- Privileged User
- Team Lead
Nobody — No users gain access to these scopes, including Workspace Admins.

Endpoints available per scope

Scopes control which endpoints and operations an API token can access.

`accountSettings:read`

Read access to account-level configuration.

Method	Endpoint	Description
GET	`accountSettings.info`	Get SSO/identity-provider configuration and session settings

`apiKeys:read`

Read access to organization-level API key records.

Method	Endpoint	Description
GET	`apiKeys.list`	List organization API keys

`auditLogs:read`

Read access to the audit log.

Method	Endpoint	Description
GET	`auditLogs.list`	Retrieve a paginated list of audit log entries

`catalog:read`

Read access to the Software Catalog — entities, types, relations, and properties.

Method	Endpoint	Description
GET	`catalog.entities.list`	List Catalog entities
GET	`catalog.entities.info`	Get details for a Catalog entity
GET	`catalog.entities.scorecards`	List Scorecards associated with an entity
GET	`catalog.entities.tasks`	Get initiative tasks for an entity
GET	`catalog.entityTypes.list`	List entity types
GET	`catalog.entityTypes.info`	Get details for an entity type
GET	`catalog.relations.list`	List relation definitions
GET	`catalog.relations.info`	Get details for a relation definition
GET	`catalog.relationEdges.list`	List relation edges between entities

`catalog:write:entities`

Write access to Catalog entities, types, and relations.

Method	Endpoint	Description
POST	`catalog.entities.create`	Create a new entity
POST	`catalog.entities.update`	Update an existing entity
POST	`catalog.entities.upsert`	Create or update an entity
POST	`catalog.entities.delete`	Delete an entity
POST	`catalog.entityTypes.create`	Create a new entity type
POST	`catalog.entityTypes.update`	Update an existing entity type
POST	`catalog.entityTypes.delete`	Delete an entity type
POST	`catalog.relations.create`	Create a new relation definition
POST	`catalog.relations.update`	Update a relation definition
POST	`catalog.relations.delete`	Delete a relation definition
POST	`catalog.relationEdges.add`	Add a relation edge between two entities
POST	`catalog.relationEdges.bulkUpsert`	Bulk-add or update relation edges
POST	`catalog.relationEdges.remove`	Remove a relation edge

`datacloud:query`

Permission to execute queries against your raw engineering data. Requires Data Studio access in addition to this scope.

Method	Endpoint	Description
POST	`studio.queryRuns.execute`	Execute a SQL query
GET	`studio.queryRuns.info`	Get the status of a query run
GET	`studio.queryRuns.results`	Retrieve results from a completed query run

`platformx:manage`

Manage PlatformX projects.

Method	Endpoint	Description
GET	`platformx.projects.list`	List PlatformX projects (paginated)
POST	`platformx.projects.create`	Create a PlatformX project

`scorecards:read`

Read access to Scorecards and Initiatives.

Method	Endpoint	Description
GET	`scorecards.list`	List Scorecards
GET	`scorecards.info`	Get details for a Scorecard
GET	`initiatives.list`	List Initiatives
GET	`initiatives.info`	Get details for an Initiative
GET	`initiatives.progressReport`	Get an Initiative progress report

`scorecards:write`

Write access to Scorecard definitions. Requires Data Studio access in addition to this scope.

Method	Endpoint	Description
POST	`scorecards.create`	Create a new Scorecard
POST	`scorecards.update`	Update an existing Scorecard
POST	`scorecards.delete`	Delete a Scorecard

`snapshots:admin`

Elevated Snapshot access: export raw data files and manage org-structure imports. The snapshots:read scope is also required for all endpoints below.

Method	Endpoint	Description
GET	`snapshots.getFile`	Download a completed Snapshot as an Excel file
POST	`orgfiles.teamHierarchy.process`	Process and import a team hierarchy
POST	`orgfiles.teamHierarchy.preview`	Preview a team hierarchy import without applying it
GET	`orgfiles.teamHierarchy.get`	Get the status or result of a team hierarchy import

`snapshots:read`

Read access to Snapshot survey data, teams, tags, and related reference data.

Method	Endpoint	Description
GET	`snapshots.list`	List all completed Snapshots
GET	`snapshots.info`	Get detailed results for a Snapshot
GET	`snapshots.driverComments.list`	List driver (sentiment) comments
GET	`snapshots.csatComments.list`	List CSAT comments
GET	`teams.list`	List teams
GET	`teams.info`	Get team details
GET	`teams.findByMembers`	Find a team by its members
GET	`teams.auditTrail`	Get team audit trail
GET	`users.findByGithubUsername`	Find a user by GitHub username

`studio:reports:read`

Read access to Data Studio Reports. Requires Data Studio access in addition to this scope.

Method	Endpoint	Description
GET	`studio.reports.list`	List Data Studio Reports
GET	`studio.reports.info`	Get configuration and metadata for a Report

`studio:reports:write`

Write access to Data Studio Reports. Requires Data Studio access in addition to this scope.

Method	Endpoint	Description
POST	`studio.reports.create`	Create a new Data Studio Report
POST	`studio.reports.update`	Update an existing Report
POST	`studio.reports.delete`	Delete a Report

`teams:manage`

Permission to manage org-structure files. The snapshots:read scope is also required.

Method	Endpoint	Description
GET	`orgfiles.list`	List previously uploaded org CSV files
POST	`orgfiles.upload`	Upload an org structure CSV file

`userGroups:read`

Read access to Frontline user groups.

Method	Endpoint	Description
GET	`userGroups.list`	List Frontline user groups
GET	`userGroups.get`	Get details for a Frontline user group

`userGroups:write`

Write access to Frontline user groups.

Method	Endpoint	Description
POST	`userGroups.create`	Create a Frontline user group
POST	`userGroups.update`	Update a Frontline user group
POST	`userGroups.delete`	Delete a Frontline user group

`users:read`

Read access to user profiles.

Method	Endpoint	Description
GET	`users.list`	List all users with profile and team details

`users:write`

Write access to user profiles and custom attributes.

Method	Endpoint	Description
POST	`users.update`	Update a user’s profile (email, start date, source system usernames, etc.)
POST	`users.attributes.update`	Upsert custom user attribute values

`workflowRuns:trigger`

Permission to trigger Self-Service Workflow runs.

Method	Endpoint	Description
POST	`workflowRuns.trigger`	Start a new Workflow Run

`workflowRuns:writeEvents`

Permission to post events and status updates into a running Workflow Run.

Method	Endpoint	Description
POST	`workflowRuns.postMessage`	Post a message to a Workflow Run
POST	`workflowRuns.addLink`	Add a link to a Workflow Run
POST	`workflowRuns.changeStatus`	Change the status of a Workflow Run

`workflows:read`

Read access to Self-Service Workflows.

Method	Endpoint	Description
GET	`workflows.list`	List available Workflows
GET	`workflowRuns.info`	Get details for a Workflow Run