Skip to main content
You sign in through your browser with your company’s single sign-on; difyctl never sees your corporate password.
External SSO is for people without a Dify account. If your email already belongs to a Dify account, this sign-in is rejected; sign in as an account user instead.

​
Sign In

1

Run the login command

difyctl auth login --host https://dify.example.com
Use the host URL your administrator gave you. A host without a scheme defaults to https://.
To skip the auto-open, pass --no-browser.
2

Sign in with your corporate identity

difyctl prints a one-time code and a verification URL, opens the URL in your default browser, and waits:
! Copy this one-time code: WDJP-XKLM
  Open: https://dify.example.com/device
The browser walks you through your company’s usual sign-in (the same one you use for other corporate tools), then asks for the one-time code.If the browser doesn’t open (normal over SSH and in headless sessions), copy the URL from the terminal and open it on any device. The code expires after 15 minutes.
3

Confirm the session

Back in the terminal:
✓ Logged in to dify.example.com as <your-email> (external SSO, issuer: <your-identity-provider>)
external SSO means you signed in through your company’s identity provider, not a Dify account. The issuer is that provider, which vouched for you.

​
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 replaces the stored token.

​
Where Your Token Lives

Signing in stores an OAuth bearer token, recognizable by its dfoe_ prefix. It represents your corporate identity on this Dify host and carries only the access your company granted it. For what that access covers, see Scope and Limitations. 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, next to the session metadata in hosts.yml. The config directory is ~/.config/difyctl on macOS and Linux and %APPDATA%\difyctl on Windows. Set DIFY_CONFIG_DIR to override it.

​
Check Who You’re Signed In As

difyctl auth whoami

<your-email> (external SSO, issuer: <your-identity-provider>)
Scripts can ask for JSON: 
difyctl auth whoami --json

{"subject_type":"external_sso","email":"<your-email>","issuer":"<your-identity-provider>"}

​
Sign Out

difyctl auth logout

✓ Logged out of dify.example.com
This removes the token and session entry from your machine. It doesn’t end your session on the server, though: that session stays active until it expires on its own. You don’t need to sign out to re-authenticate: re-running difyctl auth login against the same host replaces the session.

​
If It Fails

ProblemWhat to do
The browser never opensCopy the URL from the terminal and open it on any device. Normal over SSH and in headless sessions.
The code expiredCodes are valid for 15 minutes. Re-run difyctl auth login to get a fresh one.
Sign-in was denied (access_denied)The authorization was rejected in the browser step. Check with your administrator that your account is enabled for Dify.
The browser says your email belongs to a Dify accountExternal SSO is only for users without a Dify account. Sign in as an account user instead.
The host is rejectedOnly https:// hosts are accepted; a host without a scheme defaults to https://.
A later command fails with auth_expiredThe server expired or revoked your session. Sign in again.
For everything else, see Troubleshooting.