Skip to main content

​
Settings → Integrations: OAuth SaaS connections

The Integrations console at /settings/integrations is the dashboard surface where your organization connects SaaS providers — HubSpot, Salesforce, Shopify, Zendesk, and others — through an OAuth consent loop. Every connection you authorize here surfaces in the inbox contact panel, drives flows from inbound provider events, and lands in the audit log. This guide is the operator’s walkthrough for the full lifecycle of a SaaS connection: what the dashboard shows, how to connect a provider, how to manage and revoke the connection, and what happens when something goes wrong.

​
What the dashboard surface shows

Open Settings → Integrations. The page renders a card grid — one card per available SaaS provider — loaded from the integration catalog. Each card carries:
  • Provider name and icon — the SaaS vendor (HubSpot, Salesforce, Shopify, Zendesk, Calendly, DocuSign, Jira, and others).
  • Connection status badge — Connected (healthy), Not connected, or Errored (revoked token or provider outage).
  • Feature tags — short labels naming which Orbit capability the integration feeds (CRM context, Agent tools, Automation, Engagement).
  • Connect / Disconnect action — the primary button on the card.
Cards that are not yet available show a Coming soon badge. They go live when the provider is wired on the platform side; no action on your side until then. The grid is the marketplace — it is the same surface whether you are connecting a CRM, a commerce store, a document provider, or a scheduling tool. Each provider that supports OAuth opens the same generic consent flow; the per-provider setup steps live in the card drawer after you connect.
The Integrations hub surfaces SaaS OAuth connections. Downloadable connectors for Zapier, n8n, and Make live under the connector downloads guide — they are a separate surface.

​
Connecting a provider

The connect flow follows the same three-step pattern for every OAuth provider.

​
Step 1 — Initiate the OAuth loop

Click Connect on the provider’s card, or call the API directly:
Valid integration_id values include hubspot, salesforce, shopify, zendesk, calendly, docusign, and jira. The response returns an auth_url. Owner or admin role required, plus the integrations:write scope on the API key. This is the only step that touches provider credentials, so Orbit restricts it to admins. Redirect the browser to the auth_url. You will sign in at the provider’s consent screen and grant the requested scopes. The scopes vary by provider:

​
Step 3 — Confirm the connection

After consent, the provider redirects back and the card status flips to Connected. The drawer opens with the integration’s settings tabs. Check the connection with:
The row for your provider reports a connected state — if it shows errored, the OAuth callback did not complete; jump to Failed OAuth callback.
Provider credentials are encrypted at rest and token refresh is handled automatically. You do not need to rotate them yourself unless the provider-side credential is compromised.

​
Managing a connected integration

Once a provider is connected, open the card drawer to manage it. Three tabs cover the lifecycle:

​
Settings tab

  • Connected since — the timestamp of the last successful OAuth handshake.
  • Sync log — a history of the scheduled poll runs and webhook deliveries, with timestamps and status for each.
  • Revoke — disconnects the provider and asks the provider to delete the grant. All synced data stays in your Orbit organization; only the live connection is severed.

​
Data tab

  • Entity models — enable or disable the data models the integration syncs. For HubSpot, this includes contacts, companies, and deals. For Shopify, customers, orders, and products.
  • Pull on demand — trigger a manual sync with POST /api/v1/integrations/{id}/sync and read the synced records with GET /api/v1/integrations/{id}/data?model=contacts.

​
Health tab

  • Connection health — the live status of the OAuth grant and the last successful poll/webhook delivery. A revoked token or an expired grant shows as errored.
  • Reconnect — runs the same OAuth popup and refreshes the stored credentials in place.

​
Rotating tokens

If the provider-side credential is compromised, rotate it in the provider’s own admin panel, then reconnect from the Orbit drawer. Orbit refreshes the stored grant and the connection is live again. You do not need to disconnect first — reconnecting over an existing connection replaces the credentials.

​
Revoking a 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:
Revoking on the Orbit side is sufficient for the common case. The provider-side scopes are narrow — contact, ticket, calendar, or document access — so the provider’s own admin panel is only needed for credential rotation, not routine disconnect.

​
Error surfaces

​
Failed OAuth callback

If the OAuth callback fails — the provider’s consent screen returns an error, or the redirect back to Orbit is interrupted — the card stays in Not connected state. The drawer’s Settings tab shows the last error reason. Common causes:
  • Expired auth_url — OAuth authorization URLs are time-limited. If you waited too long before completing consent, initiate a new connect.
  • Insufficient provider permissions — the account you signed into at the provider does not have admin access to grant the requested scopes. Sign in with an admin account and retry.
  • Scope mismatch — the provider rejected one or more of the requested scopes (for example, a Shopify store with restricted API access). Check that the store or org has the required permissions on the provider side.

​
Missing scopes

Some providers allow partial scope grants — the consent screen may let you deselect individual scopes. If Orbit requested read_customers and read_orders but only read_customers was granted, the integration connects with reduced capability. The drawer’s Data tab shows which models are syncing and which are blocked due to missing scopes. Reconnect and grant the full scope set to restore the missing models.

​
Expiring-token path

Provider access tokens have a finite lifetime. Orbit refreshes them automatically using the refresh token granted during the OAuth handshake. If the refresh also fails — typically because the provider-side app was deleted or the grant was manually revoked in the provider’s admin panel — the connection status flips to Errored. The errored badge is clickable: it opens the drawer to the Health tab, which shows the last error and a Reconnect button. Reconnecting runs the OAuth popup again and replaces the stored grant.

​
Marketplace vs. public connector surface

The integrations on this page are direct OAuth connections managed by Orbit’s integration platform. They are distinct from:
  • Downloadable connectors — Zapier, n8n, and Make connectors that live outside Orbit and are downloaded from the connector downloads page. These are community-maintained workflow-engine connectors, not platform OAuth connections.
  • Custom integrations — built with Orbit’s API and webhooks by your team. These do not appear on the Integrations grid; they are managed through the API keys and webhooks consoles.
Every direct OAuth connection on the grid runs through the same platform integration service — the connect flow, credential storage, token refresh, and data sync are identical across providers. The per-provider differences (scopes, entity models, feature tags) are declared in the integration catalog and enforced at connect time.

​
Audit trail

Every connection, disconnect, and reconnect is recorded in the Audit Log at /settings/audit-log. The audit entry captures:
  • Who — the team member who initiated the action.
  • What — the provider name and the action (integration.connected, integration.disconnected, integration.reconnected).
  • When — the timestamp of the action.
  • Scope granted — the scopes authorized at connect time (for new connections and reconnects).
The audit log is searchable and exportable. Use it to answer: “who connected Salesforce last Tuesday?” or “when was the Shopify grant last rotated?”

​
Known limits

​
Write access

Not every integration supports bidirectional data flow. The current writeback surface:

​
Read-only integrations

Shopify, Calendly, and DocuSign are read-only from Orbit’s side — Orbit receives events and data from the provider but does not push writes back. This is by design: Shopify orders are placed in Shopify, Calendly events are booked in Calendly, and DocuSign envelopes are managed in DocuSign. Orbit reacts to those events with messaging and flows, but does not modify the source records.

​
Rate limits

Each provider has its own API rate limits, enforced by the provider, not by Orbit. The sync scheduler respects these limits — if a poll run hits a provider rate limit, it backs off and retries. The drawer’s Sync log shows rate-limit events with the retry timestamp.

​
Cross-references