Skip to main content
You sign in through your browser, using the OAuth 2.0 device flow; difyctl never sees your password.

​
Sign In

1

Run the login command

Pass your Dify host’s URL. On a self-hosted deployment, use the console API URL.
difyctl auth login --host https://dify.example.com
difyctl prints a one-time code, opens the verification URL in your default browser, and waits:
! Copy this one-time code: WDJP-XKLM
  Open: https://dify.example.com/device
To skip the auto-open, pass --no-browser.
If no browser opens (normal over SSH and in headless sessions), open the URL yourself on any device.
2

Approve the sign-in in your browser

In the browser tab that opens, sign in with your Dify credentials and enter the one-time code.The code expires after 15 minutes. If it expired, re-run difyctl auth login to get a fresh one.
3

Confirm the session

Back in the terminal:
✓ Logged in to dify.example.com as <your-email> (<your-name>)
  Workspace: <your-workspace>
The second line is your workspace.

​
Sign In Again

If a command fails with auth_expired (exit code 4), the server has expired or revoked your session. Run difyctl auth login again. You don’t need to sign out first, and the new sign-in refreshes your stored token.

​
Check Who You’re Signed In As

difyctl auth whoami

<your-email> (<your-name>)
To read the identity from a script, add --json: 
difyctl auth whoami --json
You’ll get the same fields as a JSON object, plus your account ID: 
{"id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","email":"<your-email>","name":"<your-name>"}

​
Sign Out

difyctl auth logout

✓ Logged out of dify.example.com
This revokes the session on the server and deletes the token and session entry from your machine. If the server-side revocation fails, your local credentials are cleared anyway.

​
Where Your Token Lives

Signing in stores an OAuth bearer token, recognizable by its dfoa_ prefix. It represents you: whatever your account can do in your workspace, the token can do from the CLI. difyctl keeps the token in your operating system’s credential store when one is available: Keychain on macOS, Credential Manager on Windows, Secret Service on Linux. If no credential store responds, it falls back to a tokens.yml file with 0600 permissions in the difyctl config directory. difyctl picks the store once when you sign in, and the session uses it from then on. Session metadata (hosts, accounts, workspaces) lives alongside the token in hosts.yml. The config directory is ~/.config/difyctl on macOS and Linux (Linux honors XDG_CONFIG_HOME) and %APPDATA%\difyctl on Windows. Set DIFY_CONFIG_DIR to override it.

​
Troubleshooting

ProblemWhat to do
The browser never opensCopy the URL from the terminal and open it on any device.
The host is rejectedOnly https:// hosts are accepted; a host without a scheme defaults to https://. For a plain http:// host (local development only), add --insecure.
A later command fails with auth_expiredYour session expired or was revoked. Sign in again.
For everything else, see the full Troubleshooting page.
Last modified on June 25, 2026