--- title: "Scopes" canonical_url: "https://docs.getdx.com/scopes/" md_url: "https://docs.getdx.com/scopes.md" last_updated: "2026-07-02" --- # Scopes In the same way that users in DX have certain [permissions](https://docs.getdx.com/permissions/), tokens have certain scopes. You can use a [Personal Access Token](https://docs.getdx.com/personal-access-tokens/) or an [Organization Token](https://docs.getdx.com/webapi/overview/) 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](https://docs.getdx.com/roles/) — 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](https://docs.getdx.com/fabric-start-guide/) customers. {% tableArgs "", "sticky" %} | Scope | All users | Snapshot Admin | Database Admin | Self-Service Admin | Workspace Admin | | ------------------------------------------------------ | :-------: | :------------: | :-------------: | :----------------: | :-------------: | | [`snapshots:read`](#snapshotsread) | ✓ | ✓ | ✓ | ✓ | ✓ | | [`catalog:read`](#catalogread) | ✓ | ✓ | ✓ | ✓ | ✓ | | [`scorecards:read`](#scorecardsread) | ✓ | ✓ | ✓ | ✓ | ✓ | | [`workflows:read`](#workflowsread) | ✓ | ✓ | ✓ | ✓ | ✓ | | [`workflowRuns:trigger`](#workflowrunstrigger) | ✓ | ✓ | ✓ | ✓ | ✓ | | [`snapshots:admin`](#snapshotsadmin) | | ✓ | | | ✓ | | [`platformx:manage`](#platformxmanage) | | ✓ | | | ✓ | | [`userGroups:read`](#usergroupsread) | | ✓ | ✓ | | ✓ | | [`userGroups:write`](#usergroupswrite) | | ✓ | ✓ | | ✓ | | [`users:read`](#usersread) | | | | | ✓ | | [`users:write`](#userswrite) | | ✓ | | | ✓ | | [`catalog:write:entities`](#catalogwriteentities) | | | ✓ | | ✓ | | [`teams:manage`](#teamsmanage) | | | | | ✓ | | [`accountSettings:read`](#accountsettingsread) | | | | | ✓ | | [`apiKeys:read`](#apikeysread) | | | | | ✓ | | [`auditLogs:read`](#auditlogsread) | | | | | ✓ | | [`workflowRuns:writeEvents`](#workflowrunswriteevents) | | | | ✓ | ✓ | | [`datacloud:query`](#datacloudquery) | | | | | | | [`studio:reports:read`](#studioreportsread) | _ | _ | _ | _ | _ | | [`studio:reports:write`](#studioreportswrite) | _ | _ | _ | _ | _ | | [`scorecards:write`](#scorecardswrite) | | | | | | _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](https://app.getdx.com/admin/general/access). ## 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`](https://docs.getdx.com/webapi/methods/snapshots.list/) | List all completed Snapshots | | GET | [`snapshots.info`](https://docs.getdx.com/webapi/methods/snapshots.info/) | Get detailed results for a Snapshot | | GET | [`snapshots.driverComments.list`](https://docs.getdx.com/webapi/methods/snapshots.driverComments.list/) | List driver (sentiment) comments | | GET | [`snapshots.csatComments.list`](https://docs.getdx.com/webapi/methods/snapshots.csatComments.list/) | List CSAT comments | | GET | [`teams.list`](https://docs.getdx.com/webapi/methods/teams.list/) | List teams | | GET | [`teams.info`](https://docs.getdx.com/webapi/methods/teams.info/) | Get team details | | GET | [`teams.findByMembers`](https://docs.getdx.com/webapi/methods/teams.findByMembers/) | Find a team by its members | | GET | [`teams.auditTrail`](https://docs.getdx.com/webapi/methods/teams.auditTrail/) | Get team audit trail | | GET | [`users.findByGithubUsername`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/snapshots.getFile/) | Download a completed Snapshot as an Excel file | | POST | [`orgfiles.teamHierarchy.process`](https://docs.getdx.com/webapi/methods/orgfiles.teamHierarchy.process/) | Process and import a team hierarchy | | POST | [`orgfiles.teamHierarchy.preview`](https://docs.getdx.com/webapi/methods/orgfiles.teamHierarchy.preview/) | Preview a team hierarchy import without applying it | | GET | [`orgfiles.teamHierarchy.get`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/catalog.entities.list/) | List Catalog entities | | GET | [`catalog.entities.info`](https://docs.getdx.com/webapi/methods/catalog.entities.info/) | Get details for a Catalog entity | | GET | [`catalog.entities.scorecards`](https://docs.getdx.com/webapi/methods/catalog.entities.scorecards/) | List Scorecards associated with an entity | | GET | [`catalog.entities.tasks`](https://docs.getdx.com/webapi/methods/catalog.entities.tasks/) | Get initiative tasks for an entity | | GET | [`catalog.entityTypes.list`](https://docs.getdx.com/webapi/methods/catalog.entityTypes.list/) | List entity types | | GET | [`catalog.entityTypes.info`](https://docs.getdx.com/webapi/methods/catalog.entityTypes.info/) | Get details for an entity type | | GET | [`catalog.relations.list`](https://docs.getdx.com/webapi/methods/catalog.relations.list/) | List relation definitions | | GET | [`catalog.relations.info`](https://docs.getdx.com/webapi/methods/catalog.relations.info/) | Get details for a relation definition | | GET | [`catalog.relationEdges.list`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/catalog.entities.create/) | Create a new entity | | POST | [`catalog.entities.update`](https://docs.getdx.com/webapi/methods/catalog.entities.update/) | Update an existing entity | | POST | [`catalog.entities.upsert`](https://docs.getdx.com/webapi/methods/catalog.entities.upsert/) | Create or update an entity | | POST | [`catalog.entities.delete`](https://docs.getdx.com/webapi/methods/catalog.entities.delete/) | Delete an entity | | POST | [`catalog.entityTypes.create`](https://docs.getdx.com/webapi/methods/catalog.entityTypes.create/) | Create a new entity type | | POST | [`catalog.entityTypes.update`](https://docs.getdx.com/webapi/methods/catalog.entityTypes.update/) | Update an existing entity type | | POST | [`catalog.entityTypes.delete`](https://docs.getdx.com/webapi/methods/catalog.entityTypes.delete/) | Delete an entity type | | POST | [`catalog.relations.create`](https://docs.getdx.com/webapi/methods/catalog.relations.create/) | Create a new relation definition | | POST | [`catalog.relations.update`](https://docs.getdx.com/webapi/methods/catalog.relations.update/) | Update a relation definition | | POST | [`catalog.relations.delete`](https://docs.getdx.com/webapi/methods/catalog.relations.delete/) | Delete a relation definition | | POST | [`catalog.relationEdges.add`](https://docs.getdx.com/webapi/methods/catalog.relationEdges.add/) | Add a relation edge between two entities | | POST | [`catalog.relationEdges.bulkUpsert`](https://docs.getdx.com/webapi/methods/catalog.relationEdges.bulkUpsert/) | Bulk-add or update relation edges | | POST | [`catalog.relationEdges.remove`](https://docs.getdx.com/webapi/methods/catalog.relationEdges.remove/) | Remove a relation edge | --- ## `scorecards:read` Read access to Scorecards and Initiatives. | Method | Endpoint | Description | | ------ | --------------------------------------------------------------------------- | --------------------------------- | | GET | [`scorecards.list`](https://docs.getdx.com/webapi/methods/scorecards.list/) | List Scorecards | | GET | [`scorecards.info`](https://docs.getdx.com/webapi/methods/scorecards.info/) | Get details for a Scorecard | | GET | [`initiatives.list`](https://docs.getdx.com/webapi/methods/initiatives.list/) | List Initiatives | | GET | [`initiatives.info`](https://docs.getdx.com/webapi/methods/initiatives.info/) | Get details for an Initiative | | GET | [`initiatives.progressReport`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/scorecards.create/) | Create a new Scorecard | | POST | [`scorecards.update`](https://docs.getdx.com/webapi/methods/scorecards.update/) | Update an existing Scorecard | | POST | [`scorecards.delete`](https://docs.getdx.com/webapi/methods/scorecards.delete/) | Delete a Scorecard | --- ## `workflows:read` Read access to Self-Service Workflows. | Method | Endpoint | Description | | ------ | --------------------------------------------------------- | ------------------------------ | | GET | [`workflows.list`](https://docs.getdx.com/webapi/methods/workflows.list/) | List available Workflows | | GET | [`workflowRuns.info`](https://docs.getdx.com/webapi/methods/workflowRuns.info/) | Get details for a Workflow Run | --- ## `workflowRuns:trigger` Permission to trigger Self-Service Workflow runs. | Method | Endpoint | Description | | ------ | --------------------------------------------------------------- | ------------------------ | | POST | [`workflowRuns.trigger`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/workflowRuns.postMessage/) | Post a message to a Workflow Run | | POST | [`workflowRuns.addLink`](https://docs.getdx.com/webapi/methods/workflowRuns.addLink/) | Add a link to a Workflow Run | | POST | [`workflowRuns.changeStatus`](https://docs.getdx.com/webapi/methods/workflowRuns.changeStatus/) | Change the status of a Workflow Run | --- ## `platformx:manage` Manage PlatformX projects. | Method | Endpoint | Description | | ------ | ------------------------------------------------------------------------- | ----------------------------------- | | GET | [`platformx.projects.list`](https://docs.getdx.com/webapi/methods/platformx.projects.list/) | List PlatformX projects (paginated) | | POST | [`platformx.projects.create`](https://docs.getdx.com/webapi/methods/platformx.projects.create/) | Create a PlatformX project | --- ## `userGroups:read` Read access to Frontline user groups. | Method | Endpoint | Description | | ------ | ------------------------------------------------------ | -------------------------------------- | | GET | [`userGroups.list`](https://docs.getdx.com/webapi/methods/user-groups.list/) | List Frontline user groups | | GET | [`userGroups.get`](https://docs.getdx.com/webapi/methods/user-groups.get/) | Get details for a Frontline user group | --- ## `userGroups:write` Write access to Frontline user groups. | Method | Endpoint | Description | | ------ | ---------------------------------------------------------- | ----------------------------- | | POST | [`userGroups.create`](https://docs.getdx.com/webapi/methods/user-groups.create/) | Create a Frontline user group | | POST | [`userGroups.update`](https://docs.getdx.com/webapi/methods/user-groups.update/) | Update a Frontline user group | | POST | [`userGroups.delete`](https://docs.getdx.com/webapi/methods/user-groups.delete/) | Delete a Frontline user group | --- ## `users:read` Read access to user profiles. | Method | Endpoint | Description | | ------ | ------------------------------------------- | -------------------------------------------- | | GET | [`users.list`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/users.update/) | Update a user's profile (email, start date, source system usernames, etc.) | | POST | [`users.attributes.update`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/orgfiles.list/) | List previously uploaded org CSV files | | POST | [`orgfiles.upload`](https://docs.getdx.com/webapi/methods/orgfiles.upload/) | Upload an org structure CSV file | --- ## `accountSettings:read` Read access to account-level configuration. | Method | Endpoint | Description | | ------ | --------------------------------------------------------------- | ------------------------------------------------------------ | | GET | [`accountSettings.info`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/apiKeys.list/) | List organization API keys | --- ## `auditLogs:read` Read access to the audit log. | Method | Endpoint | Description | | ------ | --------------------------------------------------- | ---------------------------------------------- | | GET | [`auditLogs.list`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/studio.queryRuns.execute/) | Execute a SQL query | | GET | [`studio.queryRuns.info`](https://docs.getdx.com/webapi/methods/studio.queryRuns.info/) | Get the status of a query run | | GET | [`studio.queryRuns.results`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/studio.reports.list/) | List Data Studio Reports | | GET | [`studio.reports.info`](https://docs.getdx.com/webapi/methods/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`](https://docs.getdx.com/webapi/methods/studio.reports.create/) | Create a new Data Studio Report | | POST | [`studio.reports.update`](https://docs.getdx.com/webapi/methods/studio.reports.update/) | Update an existing Report | | POST | [`studio.reports.delete`](https://docs.getdx.com/webapi/methods/studio.reports.delete/) | Delete a Report | --- --- ## Sitemap [Overview of all docs pages](/llms.txt)