Personal access tokens

A personal access token (PAT) is a user-scoped token for authenticating with the DX Web API. PATs are recommended for individual users, the DX CLI, and AI agents that act on a user’s behalf. For back-end integrations and machine-to-machine traffic, use a Web API token instead.

Compared to a Web API token, a PAT adds:

  • Audit attribution. DX records every action taken with a PAT against the user who issued the token, alongside the token name.
  • Role-scoped permissions. A PAT can only request scopes the user’s role allows. A non-admin cannot mint a PAT that updates snapshots, for example.
  • Per-token expiration. Each PAT can be set to expire after a fixed window or on a custom date.

Available scopes

See Roles & permissions for the full role list of available scopes.

Elevated user roles unlock additional scopes — a workspace admin can issue a PAT with any account-supported scope, a scorecard admin can add scorecards:write, and a self-service admin can add workflowRuns:writeEvents. The token-creation form only displays scopes the current user is allowed to grant.

Creating tokens

  1. Click your avatar in top-right of DX and select Settings.
  2. Scroll to the Personal access tokens section and click Add personal access token.
  3. Enter a Name that describes where the token will be used—for example, dx-cli-laptop or agent-experience-pipeline.
  4. Choose an Expiration: 7, 30, 60, or 90 days; a Custom date; or No expiration.
  5. Select the Scopes the token needs.
  6. Click Create.

Using tokens

Send the token in the Authorization header for any Web API request:

curl -X GET https://api.getdx.com/catalog.entities.list \
  --header 'Authorization: Bearer [PERSONAL_ACCESS_TOKEN]'

The same token works with the DX CLI (dx auth login --token <token>).

Editing or revoking tokens

  1. Click your avatar in top-right of DX and select Settings.
  2. Scroll to Personal access tokens and click the token you want to manage.
  3. Edit the Name or Scopes, or click Delete to revoke the token.

Deleting immediately revokes access for any client using the token. Expirations cannot be extended; to renew, create a new token and update the consuming client.