Connect the SaaS integrations end to end

The Integrations hub connects in two lanes. The OAuth cohort — Zendesk, Calendly, DocuSign, and Jira — opens the provider’s consent screen in a popup. The credential cohort — PostHog, Mixpanel, Freshdesk, Resend, ElevenLabs, Google Gemini, and People Data Labs — takes an API key or service-account credential in Nango’s hosted Connect UI form, with no redirect to the provider. Both lanes share one lifecycle after connect: per-provider setup, health monitoring, pause and resume, rotate, and revoke. Each provider feeds a different Orbit surface: Zendesk tickets into the inbox, Calendly bookings into reminder flows, DocuSign envelopes into tracked conversations, Jira issues into the inbox CRM panel, PostHog and Mixpanel events into CDP segments, Freshdesk tickets next to the conversations that spawned them, Resend as a transactional email lane, and ElevenLabs voices into the voice pickers.

Step 1 — Find the cards in the Integrations hub

Open Settings → Integrations. The card grid is loaded at runtime from the integration server’s provider registry via GET /api/v1/integrations/catalog, so providers your platform admin wires up appear without a code change. Orbit layers marketing copy, icons, and feature tags on top of what the registry returns; a provider the registry does not expose renders with a generic icon and automation category until the admin wires it. Each catalog entry carries the fields the card renders:

{
  "data": {
    "integrations": [
      {
        "unique_key": "zendesk",
        "provider": "zendesk",
        "display_name": "Zendesk",
        "logo_url": null,
        "status": "available",
        "syncs": ["tickets", "users"],
        "actions": []
      }
    ]
  },
  "meta": {
    "request_id": "req_01J9ZKW3E4",
    "timestamp": "2026-10-17T09:02:11.204Z"
  }
}

status is available for live providers and coming_soon for roadmap entries. Two roadmap entries remain: Google Sheets and AWS S3 show with a Coming soon badge and go live when the platform wires them; no action on your side until then. Every other card on the grid is connectable today, including the seven credential-cohort providers, which connect through the Connect UI credential form (Step 3b) instead of an OAuth popup.

Step 2 — What each integration does

Pick the integration for the capability you need. Zapier, n8n, and Make are separate connectors (see the connector downloads guide); the four below are direct OAuth connections.

Integration	What it does	Feature tags
Zendesk	Converts inbound conversations into Zendesk tickets; imports Zendesk end-users as Orbit contacts, so customer history is unified across the helpdesk and the messaging channels.	CRM context, agent tools, automation
Calendly	When an invitee books, Orbit fires SMS/WhatsApp reminders, no-show recovery, and reschedule-link flows — fully templated and channel-aware.	Engagement, automation
DocuSign	Pushes signer notifications onto SMS/WhatsApp instead of relying on DocuSign’s email-only delivery; tracks envelope status alongside conversations.	Engagement, automation
Jira	Surfaces Jira issues inside the inbox so agents link bug reports to conversations; AI agents can open and update issues on behalf of reps.	Agent tools, automation

Zendesk, Salesforce, and HubSpot are the CRM-context providers — the inbox contact panel shows synced records from whichever you connect. Connect only the systems you use.

The credential cohort

Integration	What it does	Connects with
PostHog	Syncs product analytics — events, persons, cohorts, feature flags, experiments, insights, and dashboards — so product behaviour can drive segments and automations.	Personal API key
Mixpanel	Pulls your product events into Orbit, so engagement data sits next to the conversations and campaigns it came from.	Service account username and secret, project ID
Freshdesk	Keeps tickets and agents in sync, so inbox conversations can be matched to open tickets and routed to the right people.	Helpdesk domain and agent API key
Resend	Sends Orbit transactional email through your Resend account and verified domains.	API key and a verified domain
ElevenLabs	Keeps your voices, models, conversational agents, pronunciation dictionaries, and generation history in sync, so they can be picked from inside Orbit.	API key
Google Gemini	Keeps the list of Gemini models and cached contents available to your account in sync.	Google AI Studio API key
People Data Labs	Enriches contacts and companies with verified professional and firmographic data. Lookups run on demand against your People Data Labs plan — nothing is copied into Orbit until you use it.	API key

These integrations use the generic connect flow — not the bespoke install routes that Bridge, Intercom, Slack, and WooCommerce carry. You can trigger it either from the dashboard or from the API; both open the same provider consent screen. API-key providers skip this popup entirely; connect them with the credential form in Step 3b. From the dashboard: click Connect on the integration card, sign in at the provider’s consent screen, and grant the requested scopes. When consent completes, the card status flips to Connected and the drawer opens with the integration’s settings tabs. From the API: request the auth_url and redirect the operator there:

curl -X POST https://api.orbit.devotel.io/api/v1/integrations/connect \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "integration_id": "zendesk" }'

A successful call returns 200 with the consent-screen URL to send the operator to:

{
  "data": {
    "auth_url": "https://api.nango.dev/oauth/connect/zendesk?connect_session_token=nango_connect_session_4f8b2c1d"
  },
  "meta": {
    "request_id": "req_01J9ZKW3E4",
    "timestamp": "2026-10-17T09:02:11.204Z"
  }
}

The connect_session_token inside auth_url is short-lived (Nango issues it for a single consent session, on the order of minutes). Generate it right before the operator is redirected and do not cache or reuse it. Typical failures at this step: 404 INTEGRATION_NOT_CONFIGURED when the provider has no OAuth credentials set up on the integration server, and 503 NANGO_UNAVAILABLE when the integration server is unreachable; both return { "error": { "code", "message", "status" } } with the same meta envelope. Owner or admin role required, plus the integrations:write scope on the API key. Valid integration_id values for the popup flow are zendesk, calendly, docusign, and jira; the wider OAuth cohort (Salesforce, HubSpot, and the rest of the OAuth providers) uses the same popup. Provider credentials are encrypted at rest and token refresh is handled for you.

After consent, check GET /api/v1/integrations — the row for your provider reports a connected state.

GET /api/v1/integrations returns the catalog rows with your organization’s connection state layered on. Each row carries id, name, provider, category, a connected flag, and the sync names the provider exposes — a worked page for the four popup-flow providers:

{
  "data": [
    {
      "id": "zendesk",
      "name": "Zendesk",
      "provider": "zendesk",
      "category": "helpdesk",
      "connected": true,
      "syncs": ["tickets", "users"]
    },
    {
      "id": "calendly",
      "name": "Calendly",
      "provider": "calendly",
      "category": "productivity",
      "connected": false,
      "syncs": ["event-types", "scheduled-events", "invitees"]
    },
    {
      "id": "docusign",
      "name": "DocuSign",
      "provider": "docusign",
      "category": "productivity",
      "connected": false,
      "syncs": ["envelopes", "recipients"]
    },
    {
      "id": "jira",
      "name": "Jira",
      "provider": "jira",
      "category": "helpdesk",
      "connected": false,
      "syncs": ["projects", "issues", "users"]
    }
  ],
  "meta": {
    "request_id": "req_01J9ZKX9T2",
    "timestamp": "2026-10-17T09:04:52.881Z",
    "pagination": { "cursor": null, "has_more": false, "total": 4 }
  }
}

The row flips to "connected": true once the operator finishes the consent screen. For per-sync detail (last run, next run, SUCCESS / ERROR state), use GET /api/v1/integrations/{id}/status. Run the connect → poll → confirm loop from your code:

cURL
Node.js

# 1 — request the consent URL and hand it to the operator
curl -s -X POST https://api.orbit.devotel.io/api/v1/integrations/connect \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "integration_id": "zendesk" }' | jq -r '.data.auth_url'

# 2 — after the operator grants consent, confirm the connection
curl -s https://api.orbit.devotel.io/api/v1/integrations/zendesk/status \
  -H "X-API-Key: dv_live_sk_your_key_here" | jq '.data.connected'

const API = "https://api.orbit.devotel.io/api/v1";
const headers = {
  "X-API-Key": process.env.ORBIT_API_KEY,
  "Content-Type": "application/json",
};

// 1 — request the consent URL and hand it to the operator
const { data } = await fetch(`${API}/integrations/connect`, {
  method: "POST",
  headers,
  body: JSON.stringify({ integration_id: "zendesk" }),
}).then((res) => res.json());
console.log(`Redirect the operator to: ${data.auth_url}`);

// 2 — after consent, poll until the connection confirms
for (let attempt = 0; attempt < 12; attempt++) {
  const { data: status } = await fetch(
    `${API}/integrations/zendesk/status`,
    { headers },
  ).then((res) => res.json());
  if (status.connected) {
    console.log(`Connected — ${status.syncs.length} sync(s) configured`);
    break;
  }
  await new Promise((wait) => setTimeout(wait, 5000));
}

Step 3b — Connect API-key providers via the credential form

Click Connect on a credential-cohort card and Nango’s hosted Connect UI opens in place of a provider consent screen: a short form that asks for the credential the provider issues. There is no redirect to the provider and no OAuth grant to scope — paste the key once, submit, and the card flips to Connected when the form validates. The credential is encrypted at rest, and the dashboard never echoes it back. The same role gate applies: owner or admin in the dashboard, plus integrations:write on the API key for API-driven calls. The status, sync, data, and disconnect endpoints in this guide take the same shape for credential connections, with integration_id set to the provider key — posthog, mixpanel, freshdesk, resend, elevenlabs, google-gemini, or peopledatalabs. What the form asks for, per provider:

Provider	Prerequisite
PostHog	A personal API key with read access to the project (PostHog → Settings → Personal API keys).
Mixpanel	A service account username and secret (Mixpanel → Organization settings → Service accounts) and your project ID.
Freshdesk	Your helpdesk domain (`yourcompany.freshdesk.com`) and an agent API key (Freshdesk → Profile settings → API key).
Resend	An API key with sending access, and at least one verified domain in the Resend account.
ElevenLabs	An API key (ElevenLabs → Profile → API keys).
Google Gemini	A Gemini API key from Google AI Studio.
People Data Labs	A People Data Labs API key (Settings → API keys).

If the form rejects a credential, the card reports the failed validation and nothing is stored — correct the prerequisite (a key without project read access, a missing verified domain) and connect again.

Step 4 — Finish the per-integration setup

The popup gets the account connected; each integration then has its own short setup step in the card drawer:

Integration	Post-connect step
Zendesk	Confirm the entity mapping — Open the drawer’s Data tab and enable the tickets and users models. Tickets from inbound conversations map to your Zendesk default group; end-users import as Orbit contacts.
Calendly	Pick reminder templates — Flows → Templates → Calendly: choose the reminder window (24h/1h is the default pair), the no-show recovery flow, and the reschedule-link copy.
DocuSign	Link envelopes to conversations — notifications post as their own conversation thread in the inbox, so envelope status (sent → viewed → completed) is tracked next to signer messages.
Jira	Enable the Jira agent tool — under Agents → your agent → Tools, enable the Jira toolset so AI agents can open and update issues; synced issues surface in the inbox CRM panel.

Pull records on demand any time with POST /api/v1/integrations/{id}/sync and read the synced record set with GET /api/v1/integrations/{id}/data?model=….

What lands in Orbit for credential providers

Provider	What lands in Orbit	How it is used
PostHog	Events, persons, cohorts, feature flags, experiments, insights, and dashboards, on a scheduled sync.	Product behaviour drives CDP segments and automations.
Mixpanel	Events, on a scheduled sync.	The same segment and automation surface as PostHog events.
Freshdesk	Tickets and agents.	Inbox conversations match to open tickets; routing sees which agents are available.
Resend	Nothing synced — Resend is a sending lane.	Transactional email leaves Orbit through your Resend account and verified domains.
ElevenLabs	Voices, models, conversational agents, pronunciation dictionaries, and generation history.	Synced voices are selectable in the voice pickers.
Google Gemini	Models and cached contents.	The model list available to your account, kept current.
People Data Labs	Nothing until you run a lookup.	Enrichment runs on demand against your People Data Labs plan.

Put the new providers to work

Product events into segments and automations (PostHog, Mixpanel). Once events sync, they join the CDP event stream. Build a segment on a product event — trial started, feature adopted, plan limit reached — and attach it to a flow the same way you would for a messaging event: a reminder, an upgrade nudge, a win-back. Membership stays live as each sync lands new events. On-demand enrichment (People Data Labs). The CDP console’s enrichment tab lists People Data Labs beside the other enrichment providers (GET /api/v1/cdp/enrichment-catalog), and a lookup against a contact runs through POST /api/v1/cdp/enrichment-catalog/:provider_id/broker-enrich. Each lookup draws on your People Data Labs plan, and returned fields land on the profile only when you apply them — an unused lookup copies nothing. The CDP console overview tours the tab. Ticket-to-conversation matching (Freshdesk). Synced tickets surface in the inbox contact panel next to the conversations that spawned them, so an agent answering a message sees the open ticket’s state without leaving Orbit. Transactional email (Resend). With a sending key and a verified domain connected, transactional email — receipts, one-off agent replies, notifications — leaves through your Resend account, with its delivery and engagement reporting, alongside your SMS and WhatsApp channels. Voices in the voice pickers (ElevenLabs). Synced voices appear in the voice pickers across the voice surfaces — pick the brand voice once and every voice agent uses it.

Step 5 — Monitor connection health

The card badge reports the live health of the connection: Connected (healthy) or Errored (revoked token or provider outage). The drawer’s Settings tab shows the connected timestamp and the sync log, and GET /api/v1/integrations/{id}/status exposes the same signal over the API — a connected Zendesk reports:

{
  "data": {
    "connected": true,
    "connection_id": "org_9f2c7d41",
    "provider": "zendesk",
    "created_at": "2026-08-02T14:11:05.000Z",
    "updated_at": "2026-10-17T03:00:12.000Z",
    "metadata": {},
    "syncs": [
      {
        "id": "sync_01J9ZKYB8M",
        "name": "tickets",
        "status": "SUCCESS",
        "type": "INCREMENTAL",
        "last_sync_date": "2026-10-17T03:00:12.000Z",
        "next_sync_date": "2026-10-17T04:00:12.000Z",
        "frequency": "every hour"
      },
      {
        "id": "sync_01J9ZKYC1P",
        "name": "users",
        "status": "SUCCESS",
        "type": "INCREMENTAL",
        "last_sync_date": "2026-10-17T03:00:14.000Z",
        "next_sync_date": "2026-10-17T04:00:14.000Z",
        "frequency": "every hour"
      }
    ]
  },
  "meta": {
    "request_id": "req_01J9ZKYM6V",
    "timestamp": "2026-10-17T09:10:00.310Z"
  }
}

syncs[].status is one of RUNNING, PAUSED, STOPPED, SUCCESS, or ERROR; last_sync_date is when the named sync last completed. A provider whose token was revoked — or that was never connected — answers "connected": false with "syncs": [] rather than an error, so you can poll this endpoint to confirm a connect before building on the integration. Credential connections report through the same endpoints. A synced provider — PostHog, Mixpanel, Freshdesk, ElevenLabs, Google Gemini — shows one row per synced model in syncs; a paused sync reports PAUSED and resumes on its next scheduled window or on a manual POST /api/v1/integrations/{id}/sync. An on-demand provider such as People Data Labs carries no scheduled syncs, so "connected": true with an empty syncs array is its expected steady state, not an error. A key revoked at the provider shows as Errored until you reconnect with a fresh credential. A revoked token or an expired grant shows as errored until you reconnect; reconnecting runs the same popup and refreshes the stored credentials in place.

Revoke or rotate the connection

From the dashboard: open the integration’s drawer and use Revoke in the Settings tab — Orbit disconnects and asks the provider to delete the grant. From the API, revoke with the disconnect endpoint (owner or admin role plus the integrations:write scope, same as connect):

curl -X DELETE https://api.orbit.devotel.io/api/v1/integrations/zendesk/disconnect \
  -H "X-API-Key: dv_live_sk_your_key_here"

A successful revoke returns 200:

{
  "data": { "status": "disconnected", "integration_id": "zendesk" },
  "meta": {
    "request_id": "req_01J9ZKZ2R8",
    "timestamp": "2026-10-17T09:22:40.512Z"
  }
}

Disconnecting stops scheduled syncs with the connection, so a sync that is running at that moment is simply cut off with it; its already-synced records remain readable via GET /api/v1/integrations/{id}/data?model=…. If the integration server cannot complete the revoke, the endpoint answers 502 so you know to retry — the call is safe to repeat until it confirms:

{
  "error": {
    "code": "DISCONNECT_FAILED",
    "message": "Failed to disconnect integration",
    "status": 502
  },
  "meta": {
    "request_id": "req_01J9ZKZ5H1",
    "timestamp": "2026-10-17T09:22:41.003Z"
  }
}

After a confirmed disconnect, GET /api/v1/integrations/{id}/status reports "connected": false with an empty syncs array. The provider-side permissions are narrow — ticket, user, calendar, or document scopes — so revoking on the Orbit side is enough; rotate a leaked provider credential in the provider’s own admin panel and reconnect. The credential lane rotates the same way: rotate the key in the provider’s console first, then reconnect from the card so the stored credential is replaced — Orbit keeps the old key in effect until the new one validates. The same DELETE /api/v1/integrations/{id}/disconnect revokes a credential connection, with integration_id set to posthog, mixpanel, freshdesk, resend, elevenlabs, google-gemini, or peopledatalabs.

Feature matrix — what each tag unlocks

The cards carry feature tags that name the Orbit capability the integration feeds. The complete matrix for the OAuth-popup cohort:

Integration	CRM context	Agent tools	Automation	Engagement
Zendesk	✔	✔	✔	—
Calendly	—	—	✔	✔
DocuSign	—	—	✔	✔
Jira	—	✔	✔	—

Read the tags as: CRM context — synced providers surface in the inbox contact panel and customer 360; Agent tools — AI agents can act on the provider’s records mid-flow; Automation — inbound events drive Orbit flows (tickets, reminders, envelope updates); Engagement — outbound SMS/WhatsApp touches tied to the provider’s lifecycle (bookings, envelopes).

Where the data lands — cross-references

Settings → Integrations: OAuth and credential connections — the two connect modes, WorkOS, and the complete credential-provider prerequisite table.
Connector hub — the separate Developer → Connectors catalog and credential lifecycle.
Connect HubSpot & Salesforce end to end — the CRM-context providers with deeper data models, covered in their own walkthrough.
Connect Intercom end to end — the bespoke OAuth install (signed-state round-trip), for comparison with the popup flow documented here.
CDP integration console overview — the enrichment tab and segment surfaces the PostHog, Mixpanel, and People Data Labs connections feed.
Build your first flow — wire the inbound ticket/booking/envelope events into channel flows.
Integrations API reference — connect, status, sync, data, and disconnect endpoints with worked examples.
Webhook consumer guide — how Orbit treats inbound provider webhooks generally (signature verification, retry windows, idempotency).
Downloadable connectors for Zapier, n8n, and Make — when the workflow engine lives outside Orbit.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Connect the SaaS integrations: OAuth popup and API-key credential form

Connect the SaaS integrations end to end

Step 1 — Find the cards in the Integrations hub

Step 2 — What each integration does

The credential cohort

Step 3b — Connect API-key providers via the credential form

Step 4 — Finish the per-integration setup

What lands in Orbit for credential providers

Put the new providers to work

Step 5 — Monitor connection health

Revoke or rotate the connection

Feature matrix — what each tag unlocks

Where the data lands — cross-references

​Connect the SaaS integrations end to end

​Step 1 — Find the cards in the Integrations hub

​Step 2 — What each integration does

​The credential cohort

​Step 3 — Connect via the OAuth popup

​Step 3b — Connect API-key providers via the credential form

​Step 4 — Finish the per-integration setup

​What lands in Orbit for credential providers

​Put the new providers to work

​Step 5 — Monitor connection health

​Revoke or rotate the connection

​Feature matrix — what each tag unlocks

​Where the data lands — cross-references

Connect the SaaS integrations end to end

Step 1 — Find the cards in the Integrations hub

Step 2 — What each integration does

The credential cohort

Step 3 — Connect via the OAuth popup

Step 3b — Connect API-key providers via the credential form

Step 4 — Finish the per-integration setup

What lands in Orbit for credential providers

Put the new providers to work

Step 5 — Monitor connection health

Revoke or rotate the connection

Feature matrix — what each tag unlocks

Where the data lands — cross-references