Choose a Salesforce connection method
Compare the three ways to connect a Salesforce org — SFDX Auth URL, Access Token and Connect with Salesforce — and pick the one that keeps syncing reliably.
Overview
When you click Add Salesforce Org, the Connect a Salesforce Org dialog asks you to Choose a connection method. The method decides how long the connection keeps working without your help. The key difference is whether MetaLens360 receives a refresh token, which lets it renew its Salesforce session on its own.
| Method | Label in the app | Refresh token | Best for |
|---|---|---|---|
| SFDX Auth URL | Recommended · "Long-lived · durable sync" | Yes | Any org you sync regularly or on a schedule |
| Access Token | "Quick · session-scoped" | No | A quick one-off look; expires within hours |
| Connect with Salesforce | Easiest · "One-click · browser login (OAuth)" | Yes | Production orgs, when one-click is enabled |
Before you start
- You need the Manage org/Git connections permission (Admin, Architect and DevOps roles by default).
- For SFDX Auth URL and Access Token you need the Salesforce CLI installed and browser access to the org. Allow about two minutes.
- Connect with Salesforce needs nothing on your computer, but it must be enabled for your MetaLens360 installation.
Steps
- Ask yourself whether this org will be synced more than once. If yes, rule out Access Token.
- If the org is a production org and Connect with Salesforce is available, choose it — it is the fastest durable option.
- If the org is a sandbox or uses a custom My Domain login, choose SFDX Auth URL, and log in with the right host:
- Production:
sf org login web --alias myorg - Sandbox:
sf org login web --alias myorg --instance-url https://test.salesforce.com - My Domain: pass the exact host you log in at, for example
https://acme--uat.sandbox.my.salesforce.com.
- Production:
- Reveal the auth URL with
sf org display --target-org myorg --verbose --jsonand copy thesfdxAuthUrlvalue. - Paste it into the SFDX Auth URL field, fill in the org details and click Connect Org.
Example
Priya connects acme-prod with Connect with Salesforce, which takes one click. Her acme-uat sandbox logs in at the sandbox login host, so she uses SFDX Auth URL with --instance-url https://test.salesforce.com. A colleague had added acme-dev with an access token last week — it now shows Reconnect needed, so Priya re-credentials it from the Edit dialog with SFDX Auth URL.
FAQs
Why does the access token stop working?
An access token belongs to a single Salesforce session. When that session ends, Salesforce refuses the token and MetaLens360 has no refresh token to get a new one. The Edit dialog warns about this with "This connection will keep expiring".
Can I change the method later without losing data?
Yes. Open the org's Edit dialog (pencil icon). Under Credentials, choose Sign in with Salesforce, SFDX Auth URL or Access token. The org keeps its identity, so its synced metadata and history stay attached.
Can one-click sign-in reach a sandbox?
Not from the add dialog — it always uses the standard production login. Connect the org first, then use Sign in with Salesforce in the Edit dialog and enter test.salesforce.com or your My Domain host in Login domain (optional).
Is my auth URL visible to other users?
No. It is stored encrypted and is never shown again, not even to admins.
Troubleshooting
"One-click connect isn't set up yet"
One-click sign-in is not enabled for your installation. Use SFDX Auth URL, or ask your MetaLens360 administrator to enable it.
Logging in connects to the wrong org, or fails
Sandboxes and My Domain orgs authenticate on their own host. Log in again with the correct --instance-url and copy the new auth URL.
"Login URL must be a Salesforce domain"
The Login domain (optional) field accepts only Salesforce hosts, such as test.salesforce.com or a my.salesforce.com domain. Remove any path or non-Salesforce address.
Related articles
Was this article helpful?
Related articles
- Connect a Salesforce orgAdd a Salesforce org to MetaLens360 from the Connections page using an SFDX Auth URL, an access token or one-click Salesforce sign-in, then test it.
- Fix expired org credentialsWhen an org shows Reconnect needed, Salesforce has refused its stored credentials. Re-credential it in place from the Edit dialog without losing any synced data.
- Run your first syncPull an org's metadata into MetaLens360 from the Sync Center, follow its progress, and confirm it finished and was indexed so analysis pages have data.