Connect a Salesforce org

Overview

Everything MetaLens360 shows you — drift comparisons, code analysis, org health — starts with a connected Salesforce org. You add orgs on the Connections page. Each connection stores the credentials MetaLens360 uses to read the org's metadata. MetaLens360 only reads metadata; it never deploys or changes anything in your org.

Once an org is connected, you sync it (to pull its metadata) and it is indexed (so analysis pages can read it).

Before you start

• You need the Manage org/Git connections permission (connections.manage). By default the Admin, Architect and DevOps roles have it.
• You need a Salesforce user in the target org that can log in and read metadata.
• Decide which connection method to use. If you are unsure, see Choose a Salesforce connection method. The short version: SFDX Auth URL is the most durable.

Steps

1. Open Connections from the sidebar.
2. Click Add Salesforce Org (top right). The Connect a Salesforce Org dialog opens.
3. Under Choose a connection method, pick SFDX Auth URL, Access Token or Connect with Salesforce.
4. Follow the guided steps for that method:
   • SFDX Auth URL: install the Salesforce CLI, log in to the org in your browser, run sf org display --target-org myorg --verbose --json, and paste the sfdxAuthUrl value. It must start with force://.
   • Access Token: paste the Instance URL (must start with https://) and the Access Token.
   • Connect with Salesforce: click Log in with Salesforce, sign in and approve access. MetaLens360 creates the connection when you return, so skip to step 7.
5. Fill in Name (a short identifier such as acme-prod), an optional Label, the Org Type and the Org Cloud. Org Cloud is required — it decides which group the org appears in.
6. Click Connect Org. You should see "Org connected. You can now index and compare it."
7. Back on the page, find the org under its cloud group (Commercial, Canada, GovCloud or Other) and click Test. A green "Connection verified!" message confirms MetaLens360 can reach it.

Example

Priya, a release manager, wants to compare her UAT sandbox with production. She connects acme-prod with an SFDX Auth URL (Org Type: Production, Org Cloud: Commercial), then repeats the steps for acme-uat, logging in to the sandbox with --instance-url https://test.salesforce.com. Both orgs appear under Commercial, and she clicks Test on each before her first sync.

FAQs

Can I connect a sandbox with one-click sign-in?

The Connect with Salesforce option in the add dialog always signs in at the standard production login page. For a sandbox or a My Domain login, either use SFDX Auth URL, or connect first and then open the org's Edit dialog, choose Sign in with Salesforce and enter a Login domain (optional) such as test.salesforce.com.

Can I switch between list and tile views?

Yes. Use the list/tile toggle at the top of the page. Production orgs are highlighted in both views.

What does Refresh org details do?

It asks Salesforce again for each org's ID, edition, sandbox tier and instance, and updates the details shown on each org.

What happens when I delete an org?

The delete icon removes the connection immediately, without a confirmation step. Use it with care.

Troubleshooting

"One-click connect isn't set up yet"

One-click sign-in has not been enabled for your MetaLens360 installation. Use the SFDX Auth URL method instead, or ask your MetaLens360 administrator to enable it.

"The auth URL must start with force://"

You copied the wrong value. Copy only the sfdxAuthUrl field from the sf org display ... --verbose --json output — without the --verbose flag it is not included.

"The connect request expired or was invalid — please try again."

The Salesforce sign-in took longer than about 10 minutes, or the page was reloaded mid-flow. Start again from Add Salesforce Org.

Test says the session was rejected

The stored credentials have expired. See Fix expired org credentials.

Related articles

• Choose a Salesforce connection method
• Run your first sync
• Fix expired org credentials
• Connect a Git repository