# Salesforce — CRM API: connection

> Canonical URL: https://developers.apideck.com/apis/crm/salesforce/connection

# How to connect to Salesforce

Connecting Salesforce takes two actions, in this order: choose whether this connection points at
your **Production** org or a **Sandbox**, then click **Authorize** and sign in with your Salesforce
account. There are no credentials to type or paste: the Salesforce app you authorize against
belongs to the provider of the integration, and Apideck runs the OAuth flow and keeps the
short-lived access token refreshed afterwards.

**Do the environment first.** Salesforce signs production orgs in on `login.salesforce.com` and
sandboxes on `test.salesforce.com`, and this connector sends the authorization to whichever one the
**Environment** setting names. The setting is optional and falls back to **Production** when it is
left unset, so a sandbox connection that skips it gets sent to the production sign-in page, where
the sandbox username is not recognized. Choosing it and saving takes a few seconds and avoids the
whole class of problem.

## Prerequisites

- **A Salesforce edition with API access.** Enterprise, Unlimited, Performance and Developer
  editions include it. Professional Edition needs Salesforce's paid API add-on, and entry-level
  editions (Starter Suite, and the legacy Group and Essentials editions) have no API access at all.
  If you are not sure which edition your org is on, your Salesforce administrator can confirm it.
  Checking before you start saves you a failed authorization.
- **A user with the "API Enabled" profile permission.** The System Administrator profile includes
  it. Other profiles may not, and your administrator can grant it.
- **The Salesforce user you want the connection to act as.** What the connection can read and write
  is exactly what that user can read and write: Salesforce enforces profile permissions, sharing
  rules and field-level security on API calls just as it does in the interface. A limited profile
  produces a working connection that returns only part of your data, so sign in with an account
  whose access matches what the integration needs: an Administrator profile gives full access.

## 1. Choose your environment, then save

Open the Salesforce connection in Apideck Vault. Its settings include **Environment**:

| Choose | For | Signs in on |
|---|---|---|
| **Production** | Your live Salesforce org, and free Developer Edition orgs | `login.salesforce.com` |
| **Sandbox** | A sandbox copy of a paid org: Developer, Developer Pro, Partial Copy or Full Copy | `test.salesforce.com` |

1. Pick the option that matches the org this connection is for.
2. Click **Save**.

**A Developer Edition org is not a Sandbox.** It is a free, standalone org with its own username,
and it signs in on `login.salesforce.com`, so choose **Production** for it. Pick **Sandbox** only
for a sandbox spun out of an existing paid org, which is the case where your username carries a
sandbox suffix.

## 2. Authorize with Salesforce

1. With the environment saved, click **Authorize**. Vault redirects you to the Salesforce sign-in
   page for that environment.
2. Sign in with the Salesforce account this connection should use (see Prerequisites).
3. Review the access the app asks for and click **Allow**.

The consent screen names the app registered by the provider of the integration, so the name you see
is theirs rather than "Salesforce" or the connector's. When the integration is still running on
Apideck's shared test credentials, that name is **Apideck**.

The access requested covers three things: your identity, access to Salesforce data through the API
under your own permissions, and permission to keep the connection refreshed while you are offline.
That last one is what lets the integration keep working without asking you to sign in again.

You are never asked for a redirect URL, a Consumer Key or a Consumer Secret. Those belong to the
Salesforce app held by the provider of the integration.

**Your instance URL is captured automatically.** Salesforce returns your org's instance URL as part
of the authorization, and Apideck stores it on the connection for you. There is no field to fill in
and nothing to look up: this is why the environment in step 1 is the only routing choice you make.

## After connecting

- **Token refresh is automatic.** The access token Salesforce issues is short-lived (about two
  hours). Apideck refreshes it for you, so there is nothing to re-enter while the connection is in
  regular use.
- **You may be asked to re-authorize eventually.** By default Salesforce refresh tokens do not
  expire, and a connection can run indefinitely. But an org administrator can set a refresh-token
  policy (expiry after a period of inactivity, or a fixed duration) and where such a policy is in
  place the connection will need re-authorizing when it lapses. Restore it by opening the connection
  in Vault and clicking **Authorize** again. Your Salesforce administrator can tell you whether a
  policy applies to your org.

## Disconnecting and revoking access

Either side can end the connection:

- **In Apideck Vault**, disconnect the Salesforce connection. This is the normal route and is enough
  to stop the integration.
- **In Salesforce**, revoke the app's access yourself. From your personal settings, enter *Advanced
  User Details* in the Quick Find box and select **Advanced User Details**. If that returns no
  results, enter *Personal Information* and select **Personal Information** instead. The apps you
  have granted access to are listed under **OAuth Connected Apps**, where you can click **Revoke**
  on any of them. See Salesforce's guide to
  [managing OAuth-enabled connected apps' access to your data](https://help.salesforce.com/s/articleView?id=000205444&language=en_US&type=1).

Revoking in Salesforce invalidates the tokens immediately, so the integration stops working until
you authorize again. A Salesforce administrator can also **Block** the app for the whole org: from
Setup, enter *OAuth* in the Quick Find box and select **Connected Apps OAuth Usage**. Blocking ends
every current session for the app and prevents new ones for all users until it is unblocked, so ask
your administrator if that is what you need. See Salesforce's guide to
[managing current OAuth connected app sessions](https://help.salesforce.com/s/articleView?language=en_US&id=xcloud.connected_app_manage_current_sessions.htm&type=5).

## Troubleshooting

**Authorization fails with `API_DISABLED_FOR_ORG`.**
Your org's edition does not have API access. This is an edition-level entitlement, not a setting
your integration can change: Professional Edition needs Salesforce's paid API add-on, and
entry-level editions have no API access to enable. Ask your Salesforce administrator to confirm the
edition and, if it is Professional, whether the API add-on is active.

**Sign-in is rejected, or the sign-in page loops back without connecting.**
Two things to check, in order. First, the **Environment** setting: if it was left unset or set to
**Production** while you are connecting a sandbox, you were sent to `login.salesforce.com`, which
does not know your sandbox username. Set it to **Sandbox**, click **Save**, then **Authorize**
again. Second, that your user has the **API Enabled** permission; without it Salesforce refuses the
API grant even though the password is correct. Your administrator can grant it.

**The connection saved, but some records or fields are missing.**
This is almost always the authorizing user's access rather than a broken connection. Salesforce
applies that user's profile permissions, sharing rules and field-level security to every API call,
so records they cannot see and fields they cannot read do not come through. Ask your administrator
to widen that user's access, or re-authorize with an account that already has it.

**The connection worked and later stopped.**
The usual causes, in order:

1. A refresh-token policy in your org expired the connection: open it in Vault and click
   **Authorize** again.
2. The Salesforce user who authorized it was deactivated, or their profile lost the **API Enabled**
   permission: re-authorize with an account that has the access.
3. Someone revoked the app's access in Salesforce, from personal settings or org-wide: authorize
   again if that was not intended.
4. The Salesforce app credentials behind the integration changed. That sits with the provider of the
   integration, not with you, and affects every connection using them. Report it to them.

**The consent screen shows a name I do not recognize.**
It shows the app registered by the provider of the integration, or **Apideck** when their integration
is running on shared test credentials. If neither matches who you expect to be connecting to, stop
and check with the provider of the integration before granting access.

Still stuck? Contact [Apideck Support](https://help.apideck.com/en/articles/7774658).


[API reference](https://developers.apideck.com/apis/crm/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/crm/coverage)