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 an organization token instead.

Compared to an organization 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

For a complete breakdown of scopes — including role mappings and what each scope grants access to — see Scopes.

When you create a PAT, you select from the scopes your current role permits. The scopes enforced at request time are the intersection of the token’s selected scopes and the scopes your account currently allows — meaning:

  • Role downgrade. If your role is reduced after creating a token, the token automatically loses any scopes your new role no longer permits.
  • Role upgrade. If your role is upgraded, the token does not automatically gain new scopes. Create a new token (or edit the existing one) and explicitly add the additional scopes.
  • Hard ceiling. A token can never have more access than your current role allows, regardless of what was selected at creation time.

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.