> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Authenticate > Learn how to authenticate the Docusign CLI using OAuth PKCE. Log in to the developer or production environments and switch between accounts. 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](https://www.docusign.com/developers/sandbox). * 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](https://support.docusign.com/s/contactSupport) to request access. ## Command usage `$ ds auth login [options]` The following options are available: | Option | Shorthand | Description | Accepted values | Default value | | --------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------- | | `--environment` | `-e` | The target Docusign environment to authenticate against. | `production, demo` | `demo` | | `--port` | `-p` | The local port the CLI uses to host a temporary server to receive the OAuth callback. | An available port number (for example, 8081) | Auto-selects between 8080 and 8085 | | `--no-browser` | N/A | Prevents the CLI from automatically opening the browser. The login URL is printed to the console so you can open it manually on any device. | N/A | Browser opens automatically | | `--help` | `-h` | Displays help for the command. | N/A | N/A | ## 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. 1. The CLI opens your default browser. 2. Enter your account credentials. The browser displays the message **Authentication successful**. 3. Return to the CLI. 4. 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. 5. 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](/docusign-cli/configure-agreement-types-and-fields). * To see the agreements and fields already available in your account, [retrieve the standard and custom catalogs](/docusign-cli/configure-agreement-types-and-fields/retrieve-standard-and-custom-catalogs). * Get the details about [building a manifest and providing training documents](/docusign-cli/configure-agreement-types-and-fields/create-package) for your custom configuration.