Salesforce DX Developer Guide

How Salesforce Developer Experience (DX) Tooling Changes the Way You Work
Provide Developers Access to Salesforce DX Tools
Project Setup
Authorization
Authorize an Org Using a Browser
Authorize an Org Using the JWT Flow
Create a Private Key and Self-Signed Digital Certificate
Create an External Client App in Your Org
Create a Connected App in Your Org
Use the Default Connected App Securely
Use an Existing Access Token
Authorize an Org Using Its SFDX Authorization URL
Authorization Information for an Org
Log Out of an Org
Metadata Coverage
Scratch Orgs
Sandboxes
Track Changes Between Your Project and Org
Work with Data
Salesforce DX MCP Server and Tools (Beta)
Development
Build and Release Your App
Unlocked Packages
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Create a Connected App in Your Org

Salesforce CLI requires either an external client app (preferred) or connected app in the org that you're authorizing.

Create a connected app in your org only if it's your Dev Hub and you plan to later create scratch orgs or sandboxes with the org create scratch|sandbox commands. Otherwise, create an external client app, which is the preferred integration framework.

Connected apps are being deprecated. We plan to provide the information in this topic only until the requirement to use connected apps for sandbox or scratch org creation is removed.

Warning

A connected app is a framework that enables an external application, in this case Salesforce CLI, to integrate with Salesforce using APIs and standard protocols, such as OAuth. We provide a default connected app when you authorize an org with the org login web command.

You must have the Approve Uninstalled Connected Apps user permission to complete this task. Org administrators have the permission by default.

Important

In the task below, the steps marked Required for JWT are required only if you’re creating a connected app to use with the org login jwt command. In this case you also need a file that contains a digital certificate, such as server.crt. The steps are optional if you’re creating a connected app to use with org login web.

  1. Contact Salesforce Customer Support to enable the creation of connected apps in your org.
    Creating connected apps is now disabled by default, because connected apps are being deprecated. If you need to create a connected app, Salesforce Customer Support must enable an org perm in your org. This is a one-time process per org. See New connected apps can no longer be created in Spring ‘26.
  2. Log in to your org.
  3. From Setup, in the Quick Find box, enter External Client Apps, and then select Settings.
  4. Turn on Allow creation of connected apps and click Enable.
  5. Click New Connected App.
  6. Update the basic information as needed, such as the connected app name and your email address.
  7. Select Enable OAuth Settings.
  8. For the callback URL, enter http://localhost:1717/OauthRedirect.

    If port 1717 (the default) is already in use on your local machine, specify an available one instead. Then update your sfdx-project.json file by setting the oauthLocalPort property to the new port. For example, if you set the callback URL to http://localhost:1919/OauthRedirect:

    1"oauthLocalPort" : "1919"
  9. (Required for JWT) Select Use digital signatures.
  10. (Required for JWT) Click Choose File and upload file that contains your digital certificate, such as server.crt.
  11. Add these OAuth scopes:
    • Manage user data via APIs (api)
    • Manage user data via Web browsers (web)
    • Perform requests at any time (refresh_token, offline_access)
  12. Click Save, then Continue.
  13. Click Manage Consumer Details.
    If prompted, verify your identity by entering the verification code that was automatically sent to your email address.
  14. Click Copy next to Consumer Key because you need it later when you run an org login command. Depending on whether you specify that it's required, also copy the Consumer Secret.
  15. Click Back to Manage Connected Apps.
  16. Click Manage.
  17. Click Edit Policies.
  18. In the OAuth Policies section, for the Refresh Token Policy field, click Expire refresh token after: and enter 90 days or less.
    Setting a maximum of 90 days for the refresh token expiration is a security best practice. To continue running CLI commands against an org whose refresh tokens have expired, reauthorize it with the org login web or org login jwt command.
  19. In the Session Policies section, set Timeout Value to 15 minutes.
    Setting a timeout for access tokens is a security best practice. Salesforce CLI automatically handles an expired access token by referring to the refresh token.
  20. (Required for JWT) In the OAuth Policies section, select Admin approved users are pre-authorized for permitted users, and click OK.
  21. Click Save.
  22. (Required for JWT) Click Manage Profiles, select the profiles that are pre-authorized to use this connected app, and click Save. Similarly, click Manage Permission Sets to select the permission sets. Create permission sets if necessary.
To specify the consumer key, use the --client-id flag of the org login commands. For example, if your consumer key is 04580y4051234051 and you’re authorizing a Dev Hub org by logging into it from a browser, run this command in a terminal (macOS and Linux) or command prompt (Windows):
1sf org login web --client-id 04580y4051234051 --set-default-dev-hub --alias my-hub-org

If you specifed in the connected app that the web login flow requires a client (consumer) secret, the command prompts you for it. The command then opens the login page for you to add your org credentials.

See the reference for org login web and org login jwt for more examples.