#Current status

The provider is a first-class member of the CRMProvider union ("zoho" | "salesforce" | "hubspot"). It has an OAuth authorize-URL builder, a shared OAuth callback route that stores the connection, the SalesforceConnector implementation, and a field-mapping UI. Zoho, HubSpot, and Salesforce are all live today.

#Connector capabilities

SalesforceConnector advertises a capabilities object that the platform reads to decide which sync actions to offer. For Salesforce every flag is true, and each corresponds to a working method.

pushLeadsboolean

Create Salesforce Lead records from Olyron leads via POST /sobjects/Lead.

pullLeadsboolean

Fetch Salesforce Leads into Olyron via a SOQL query.

pushNotesboolean

Attach a note to a Salesforce record using the legacy Note object.

pushTasksboolean

Create Salesforce Task activities via POST /sobjects/Task.

pushDealsboolean

Create Salesforce Opportunity records from Olyron deals.

pullDealsboolean

Fetch Salesforce Opportunities into Olyron via SOQL.

webhooksboolean

Connector is declared webhook-capable for inbound change events.

bidirectionalboolean

Supports two-way sync (push and pull) rather than one-way push.

vendorSyncboolean

Push normalized vendor enrollment data into Salesforce as a completed Task.

#How the connect flow works

The connect experience follows the OAuth 2.0 pattern shared by every CRM connector in Olyron CRM. It starts on the provider connect page and finishes at a shared callback route that persists the connection.

1. 1
   Open the connect page

   From CRM Integrations (/dashboard/settings/integrations) choose Salesforce, which routes to /dashboard/settings/integrations/salesforce/connect. This page also lets you toggle Vendor enrollment sync and pick which vendor fields to include.
2. 2
   Authorize

   Clicking Authorize builds a CSRF state token of the form ${tenant.id}:${Date.now()}, stores it (and your vendor-sync preferences) in sessionStorage, and redirects the browser to the Salesforce authorize URL.
3. 3
   Grant access in Salesforce

   Salesforce prompts you to sign in and approve the requested scopes (api refresh_token offline_access), then redirects back to Olyron with an authorization code and the state.
4. 4
   Token exchange & storage

   The callback at /api/crm-connectors/salesforce/callback calls the connector's connect() method, which POSTs the code to https://login.salesforce.com/services/oauth2/token. The token response includes an instance_url that is stored on the connection and used as the API base. A crm_connections row is inserted with status active.
5. 5
   Map fields

   On success you are redirected to /dashboard/settings/integrations/salesforce/map-fields?connection_id=<id>&success=true to align Olyron fields with Salesforce fields.

https://login.salesforce.com/services/oauth2/authorize
  ?response_type=code
  &client_id=<SALESFORCE_CLIENT_ID>
  &redirect_uri=<origin>/api/crm-connectors/salesforce/callback
  &scope=api refresh_token offline_access
  &state=<tenantId>:<timestamp>

Token exchange, refresh, and disconnect

• connect() performs the authorization_code grant against /services/oauth2/token and returns access_token, refresh_token, and instance_url. When Salesforce returns issued_at, expires_at is recorded as roughly two hours later; tokens are otherwise treated as short-lived and refreshed on demand.
• refreshToken() performs the refresh_token grant. Salesforce does not return a new refresh token here, so only the access token (and instance_url) are updated.
• disconnect() makes a best-effort POST to /services/oauth2/revoke; failures are ignored because the token may already be invalid.

#Callback endpoint reference

A single dynamic route handles the OAuth return for all providers. There is no dedicated Salesforce route — the [provider] segment resolves to salesforce.

The handler calls supabase.auth.getUser() and, if there is no session, redirects to /sign-in?redirect=/dashboard/settings/integrations. The instance_url returned from the token exchange is stored on the connection, and both tokens are wrapped with encryptToken() before being written to crm_connections.

#Token security at rest

Access and refresh tokens are stored in crm_connections.access_token_enc and refresh_token_enc. encryptToken() / decryptToken() in src/lib/crm-connectors/sdk.ts use AES-256-GCM (authenticated encryption) with a 32-byte key derived from CRM_ENCRYPTION_KEY.

Algorithmaes-256-gcm

Authenticated encryption providing confidentiality plus tamper detection via the GCM auth tag.

Formatstring

v1:gcm:<iv_b64>:<tag_b64>:<ciphertext_b64> — a random 12-byte IV per token.

KeyCRM_ENCRYPTION_KEY

SHA-256 of the env value yields the 32-byte key. Required in production; a warned insecure fallback is used only in non-production.

Legacy tokensbase64

Tokens written before this change are plain base64. They remain readable and are transparently re-encrypted to AES-GCM on the next write.

#Data operations (REST & SOQL)

All data calls target the org's REST API at ${instance_url}/services/data/v60.0, authenticated with Authorization: Bearer <access_token>. The base URL comes from the instance_url stored on the connection; if it is missing, the connector throws. HTTP requests run through a shared helper that retries with exponential backoff and tolerates empty/204 responses.

Leads → Salesforce Lead

• Create: pushLead() POSTs to /sobjects/Lead. Company is a required Salesforce field, so the connector defaults it to custom_fields.company when present, otherwise "(Individual)". Field mappings and custom fields are merged in, and null/undefined values are stripped before send.
• Update: updateLead() PATCHes /sobjects/Lead/{id}, which returns 204 No Content. Only the fields present in the patch are sent.
• Fetch: fetchLeads() runs a SOQL query via GET /query?q=SELECT ... FROM Lead selecting Id, FirstName, LastName, Email, Phone, Status, LeadSource. search matches on Email or LastName; status filters on Status; results use LIMIT (default 200) and optional OFFSET.

Notes → legacy Note object

pushNote() POSTs a single record to /sobjects/Note with { Title, Body, ParentId }. ParentId links the note directly to the parent record (the lead or contact), and Title defaults to "Note" when none is supplied.

Tasks → Salesforce Task

createTask() POSTs to /sobjects/Task. The relationship field depends on the related object type: person records (lead or contact) are linked via WhoId, while other objects (e.g. an Opportunity) use WhatId. Status defaults to "Not Started" and due_date becomes the date-only ActivityDate. Priority is mapped:

Deals → Salesforce Opportunity

• Create: pushDeal() POSTs to /sobjects/Opportunity. Name, StageName, and CloseDate are required by Salesforce, so StageName defaults to "Prospecting" and CloseDate defaults to 30 days from now (date-only). Amount and Probability are optional.
• Update: updateDeal() PATCHes /sobjects/Opportunity/{id}, returning 204 No Content.
• Fetch: fetchDeals() runs SOQL against Opportunity selecting Id, Name, Amount, StageName, CloseDate, Probability, with an optional StageName equality filter and a Name LIKE '%...%' search, plus LIMIT (default 200) and optional OFFSET.

#Connection record & field mapping

Every linked org is one row in the crm_connections table (typed as CRMConnection in src/types/index.ts).

idstring

Connection primary key.

tenant_idstring

Owning tenant; derived from the OAuth state.

provider"salesforce"

CRM provider discriminator.

auth_type"oauth2"

Salesforce connections are always OAuth 2.0.

access_token_encstring

AES-256-GCM encrypted access token.

refresh_token_encstring | null

AES-256-GCM encrypted refresh token (Salesforce refresh tokens do not expire unless revoked).

expires_atstring | null

Access token expiry timestamp (approximate; tokens are refreshed on demand).

instance_urlstring | null

Org-specific API host used as the REST base (e.g. https://na1.salesforce.com).

status"active" | "inactive" | "error"

Connection health.

last_sync_atstring | null

Last successful sync; shown as “Never” until a sync runs.

Salesforce object mapping

#Vendor enrollment sync

Beyond standard CRM objects, syncVendorEnrollment(payload) records a normalized insurance/benefits enrollment change in Salesforce. It creates a completed Task (Status "Completed") whose Subject summarizes the vendor and whose Description is a formatted summary of the enrollment (member, plan, status, change type, effective/termination dates, and any change description).

• The Task is linked to the member via WhoId when payload.member_external_id is present.
• ActivityDate is set from effective_date (falling back to today), date-only.
• On the connect page you can enable vendor sync and choose which attributes to include: Plan Name, Status, Effective Date, Termination Date, and Premium (Plan Name, Status, and Effective Date are enabled by default).

interface VendorEnrollmentSyncPayload {
  vendor_id: string;
  vendor_name: string;
  vendor_code: string;
  member_external_id?: string;
  member_name?: string;
  member_email?: string;
  enrollment_plan?: string;
  enrollment_status?: string;
  effective_date?: string;
  termination_date?: string;
  change_type?: string;
  change_description?: string;
  raw_payload?: Record<string, any>;
}

#Setup & troubleshooting

Environment variables

SALESFORCE_CLIENT_IDenv

Consumer Key from your Salesforce Connected App. Read by getAuthUrl to build the authorize URL and by connect()/refreshToken() during the token exchange.

SALESFORCE_CLIENT_SECRETenv

Consumer Secret used during the authorization_code and refresh_token grants.

SALESFORCE_REDIRECT_URIenv

Registered callback; must match /api/crm-connectors/salesforce/callback.

CRM_ENCRYPTION_KEYenv

Secret used to derive the AES-256-GCM key for token encryption at rest. Required in production.