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
Team Lead
Snapshot Analyst
Snapshot Observer
Data Integrator
Scorecard admin
Priviledged User
Interviewer
Finance Manager

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
`snapshots:read`	✓	✓	✓	✓	✓
`catalog:read`	✓	✓	✓	✓	✓
`scorecards:read`	✓	✓	✓	✓	✓
`workflows:read`	✓	✓	✓	✓	✓
`workflowRuns:trigger`	✓	✓	✓	✓	✓
`snapshots:admin`		✓			✓
`platformx:manage`		✓			✓
`userGroups:read`		✓	✓		✓
`userGroups:write`		✓	✓		✓
`users:read`					✓
`users:write`		✓			✓
`catalog:write:entities`			✓		✓
`teams:manage`					✓
`accountSettings:read`					✓
`apiKeys:read`					✓
`auditLogs:read`					✓
`workflowRuns:writeEvents`				✓	✓
`datacloud:query`
`studio:reports:read`	_	_	_	_	_
`studio:reports:write`	_	_	_	_	_
`scorecards:write`

_Data Studio scopes (listed as studio:_ above) are available to any user whose account has Data Studio enabled and who has been granted personal access to it, regardless of role. Access to Data Studio is defined in Admin > Access & Visibility.

Endpoints available per scope

Scopes control which endpoints and operations a Web API token can access.

`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

`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

`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

`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

`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

`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

`platformx:manage`

Manage PlatformX projects.

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

`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

`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

`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

`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

`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