Authenticate
The auth login command authenticates the Docusign CLI against a Docusign environment using the OAuth Proof Key for Code Exchange (PKCE) flow. When you run the command, the CLI opens a browser-based login page, retrieves an OAuth token, and stores your credentials locally for use in subsequent commands.
You must authenticate before running any other Docusign CLI commands. You must also re-authenticate when:
- You switch between environments or accounts
- The access token expires, eight hours after authentication
Prerequisites
Before authenticating, confirm the following:
- You have a Docusign developer or production account. Docusign recommends using the CLI in a developer account first. You can fill out a form to create a free developer account.
- The account that you use for login has the plan items and permissions required to configure Agreement Manager. All new developer accounts have Agreement Manager permissions. Production Agreement Manager access depends on your account plan. If you have an existing developer account that does not have Agreement Manager access, contact Docusign Support to request access.
Command usage
$ ds auth login [options]
The following options are available:
Example commands
Log in to the developer environment
The default behavior for the auth login command is to log in to the developer (demo) environment. The CLI authenticates against the developer environment and opens the browser automatically.
$ ds auth login
Log in to the production environment
Use the -e flag to specify the production environment.
$ ds auth login -e production
Log in without opening a browser
Use the --no-browser flag when running the CLI on a remote server or an environment without a graphical user interface.
$ ds auth login --no-browser
Login steps after running the command
Follow these steps after you run the auth login command. These steps apply regardless of which command options you use.
- The CLI opens your default browser.
- Enter your account credentials. The browser displays the message Authentication successful.
- Return to the CLI.
- If the account you supplied has multiple users, the CLI lists the users. Select the user that you want to associate your Docusign CLI workspace with.
- The CLI displays the authenticated account and user, the access token expiration date and time, and information about Agreement Manager feature availability in your account.
Switching environments and accounts
The Docusign CLI stores credentials for the most recently authenticated environment and account. To switch to a different environment or account, run auth login again with the appropriate options.
You must re-authenticate in the following situations:
- Switching from the developer environment to production: After validating your configuration in a developer account, authenticate against your production account before uploading or running commands that affect production data.
- Copying a configuration between accounts: When you retrieve a configuration from a source account and deploy it to a target account, authenticate once for the source account to retrieve the configuration, and then authenticate again for the target account before deploying. This pattern applies to both developer-environment-to-production deployments and account-to-account portability scenarios.
Frequently asked questions
Which OAuth flow does the CLI use for authentication?
The CLI uses the OAuth Proof Key for Code Exchange (PKCE) flow. This flow is designed for public clients such as CLI tools, where a client secret cannot be stored securely. It handles the browser-based login, token retrieval, and local storage of credentials automatically.
What happens if port 8080 is already in use?
By default, the CLI auto-selects an available port between 8080 and 8085 to host the temporary OAuth callback server. If you need to specify a port explicitly - for example, to satisfy a firewall rule - use the --port option and provide an available port number between 8080 and 8085.
Can I use the CLI on a server without a graphical user interface?
Yes. Use the --no-browser flag when running the CLI in a headless environment. The CLI prints the login URL to the console, and you can complete the login by opening that URL in a browser on any other device.
Do I need to log in again after my session expires?
Yes. If your session token expires, subsequent commands will return an authentication error. Run ds auth login again to re-authenticate. You must also re-authenticate any time you switch environments or accounts.
Which account permissions are required to use the CLI?
The account you authenticate with must have the plan items and permissions required to configure Agreement Manager enabled. All new developer accounts have Agreement Manager permissions. Production Agreement Manager access depends on your account plan. The Docusign CLI checks your production account plan after authentication and displays a notification if the plan does not include the required Agreement Manager permissions.
Next steps
- Learn how to define custom agreements and fields.
- To see the agreements and fields already available in your account, retrieve the standard and custom catalogs.
- Get the details about building a manifest and providing training documents for your custom configuration.