Personal access tokens are available from Dify 1.20.0.
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 ashttps://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-idinstead.
difyctl:-
A CI job: install
difyctlin the job, store the token as a secret in your CI system, and setDIFY_TOKENfrom that secret. - A coding agent: set the variables where your agent starts, such as the shell you launch it from. Keep the token out of the chat, where anything you type passes through your agent’s model.
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:
-
If it only manages workspaces, run
difyctl describe accountto list the workspaces the token can manage, and check that the job’s workspaces are among them.
Troubleshooting
For more errors, see Troubleshooting on Results, Errors, and Exit Codes.