Skip to main content
Personal access tokens are available from Dify 1.20.0.
A personal access token lets difyctl act as you without a sign-in. It differs from a sign-in in how long it lasts and what it can run: Give a token to a CI job or coding agent that runs apps or sets up integrations, so it keeps working without anyone renewing a sign-in. For work that changes apps, such as updating an app from a DSL file or publishing it, pass a job a sign-in token instead, and leave a coding agent on your own sign-in.

Choose the Account and Scopes

Give each job its own personal access token, so you can change, replace, or delete it without touching the other jobs. For a job the team depends on, create the token from an account used only for automation. The job then keeps working when your own access changes, and its runs are easy to tell apart from yours. Add the account to each workspace the job works in, with the role the job’s commands need there. When you create the token on the account page, give it only the scopes the job needs. You can edit them later: the change applies from the token’s next command, with no new token to give the job.
Each command below also needs what the Command Index lists for it, such as a role or the app’s Service API access.

Let the Token Run Apps

Use the Resources scope for a job that does any of these:

Let the Token Set Up Integrations

Use the Manage workspaces scope for a job that does any of these:

Give the Token to difyctl

1

Look Up the Workspace ID

The job needs the ID of each workspace it works in if it lists apps or sets up integrations. To look up the IDs, run difyctl get workspace, and copy each workspace’s id. A coding agent can look the IDs up itself.
2

Set the Environment Variables

  • DIFY_SERVER: the address you open Dify at, such as https://dify.example.com.
  • DIFY_TOKEN: the token.
  • DIFY_WORKSPACE_ID: the workspace ID, if you looked one up. If the job works in more than one workspace, give each command the ID of its workspace with --workspace-id instead.
How you set them depends on what runs difyctl:While DIFY_TOKEN is set, commands use these variables instead of your saved sign-in.
3

Check the Token

In a shell with these variables set, check that the token reaches what the job uses:
  • If the token can run apps, describe an app the job uses, with the app’s ID:
    Copy the app’s ID from its address (/app/<app-id>/…) in Studio. Or, if you’ve set DIFY_WORKSPACE_ID, run difyctl get console_app to list it.
  • If it only manages workspaces, run difyctl describe account to list the workspaces the token can manage, and check that the job’s workspaces are among them.
If the check fails, find its message in Troubleshooting.

Troubleshooting

For more errors, see Troubleshooting on Results, Errors, and Exit Codes.
Last modified on November 18, 2026