---
title: "Get Salesforce OAuth connect URL"
method: GET
path: "/v1/connect/salesforce"
tags: ["Connect"]
---

# Get Salesforce OAuth connect URL

`GET /v1/connect/salesforce`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/connect/salesforce`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Connect-Token`

Initiates OAuth (authorization code with PKCE) for a Salesforce org. Salesforce is a connect-only CRM platform: inbox contacts are matched to Contacts and Leads, and each day of conversation is logged as a Task.

The org must have the Zernio Salesforce package installed first: it carries the app Salesforce authorizes. Production orgs install it from `https://login.salesforce.com/packaging/installPackage.apexp?p0=04tfj000000llzZAAQ`, sandboxes from the same path on `test.salesforce.com`. Without it the redirect carries `error=salesforce_package_not_installed`.

One Salesforce org can be connected per profile. Connecting a different org to a profile that already has one redirects with `error=salesforce_profile_has_org`.

### Flow

1. Redirect the user to `authUrl`.
2. After authorization, Salesforce returns the browser to Zernio's internal callback.
3. Zernio redirects to `redirect_url` (or the dashboard when omitted).

On success the redirect carries `connected=salesforce`, `profileId`, `accountId` and `username`. On failure it carries `error`, `platform=salesforce` and `error_message`.

Reconnecting the same org and profile updates the stored connection in place and keeps its settings.

Requested scopes: `api`, `refresh_token`, `id`.

## Query parameters

- `profileId` string, required
- `environment` 'production' | 'sandbox'
- `redirect_url` string

## Response `200`

OAuth authorization URL and authenticated state

- object
  - `authUrl` string, uri, required: Salesforce URL to open in the user agent.
  - `state` string, required: Authenticated, expiring OAuth state handled by the callback.

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `402`: Payment method or enterprise contract required: the authenticated account hit a billing gate before the connection could proceed. Switch on `reason` to render the right prompt: - `free_tier_exceeded`: the team has connected more accounts than the free tier allows. Add a payment method to continue (billed per additional connected account). - `twitter_passthrough`: connecting an X account requires a card on file, even the 1st one, because X API calls are passed through per call. Prepaid-balance accounts never get it: they pay X calls from the balance. - `enterprise_required`: the team's enterprise contract sets a connected-account cap and it has been reached. Self-service teams have NO cap (the $1/account rate continues at any scale). The user already has a card on file; this gate is about contract terms. - `card_verification_required`: the card on file was flagged at add time (prepaid, or issued in a different country than the billing address). A one-time verification charge of `details.verification_amount_cents` (USD) is pending; it is credited to the team's usage balance, not a fee. **What to do:** redirect the end-user to `dashboard_url`. - `free_tier_exceeded`, `twitter_passthrough`, `card_verification_required`: it opens the Zernio billing page (the add-payment-method drawer, or the verification step). The request succeeds once the card is on file (or verified, or paid). - `enterprise_required`: it opens the enterprise contact form (not the billing tab), to adjust the contract's limit.
- `403`: API key does not have access to this profile, or the key is read-only.
- `404`: Profile not found or access denied.
- `503`: Salesforce OAuth is not configured.

## Changes

- **2026-11-17** `716f6dff13e7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/connect/salesforce/get.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/426793b18d45?raw)
