> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Settings → Integrations: OAuth SaaS connections end to end

> Walk through the Integrations hub at /settings/integrations — connect HubSpot, Salesforce, Shopify, and other SaaS providers via OAuth, manage connected integrations, handle failed callbacks, and understand the audit trail for every connection.

# 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.

<Info>
  The Integrations hub surfaces SaaS OAuth connections. Downloadable connectors for Zapier, n8n, and Make live under the [connector downloads guide](/guides/connectors-download) — they are a separate surface.
</Info>

## 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:

```bash theme={null}
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": "hubspot" }'
```

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.

### Step 2 — Grant consent at the provider

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:

| Provider | Key scopes granted | What Orbit can do with them |
| - | - | - |
| **HubSpot** | `crm.objects.contacts.read`, `crm.objects.contacts.write`, `crm.objects.companies.read`, `timeline` | Sync contacts and companies bidirectionally; push Orbit events as timeline entries |
| **Salesforce** | `api`, `refresh_token`, `offline_access` | Sync contacts, leads, and accounts; push Orbit events into the org |
| **Shopify** | `read_customers`, `read_orders`, `read_checkouts`, `read_products` | Receive customer, order, and checkout events in real time; build cart-recovery flows |
| **Zendesk** | `read`, `write` | Convert conversations into tickets; import end-users as Orbit contacts |
| **Calendly** | `read:events` | Fire SMS/WhatsApp reminders, no-show recovery, and reschedule-link flows |
| **DocuSign** | `signature` | Push signer notifications onto SMS/WhatsApp; track envelope status alongside conversations |
| **Jira** | `read:issue`, `write:issue` | Surface issues in the inbox CRM panel; let AI agents open and update issues |

### 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:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/integrations \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

The row for your provider reports a `connected` state — if it shows `errored`, the OAuth callback did not complete; jump to [Failed OAuth callback](#failed-oauth-callback).

<Check>
  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.
</Check>

## 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:

```bash theme={null}
curl -X DELETE https://api.orbit.devotel.io/api/v1/integrations/hubspot/disconnect \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

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](/guides/connectors-download). 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](/guides/api-keys-end-to-end).

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:

| Provider | Reads | Writes | Write surface |
| - | - | - | - |
| **HubSpot** | Contacts, companies, deals | Contacts | Contact field updates, lifecycle stage changes, timeline events |
| **Salesforce** | Contacts, leads, accounts | Contacts, leads | Contact and lead field updates |
| **Shopify** | Customers, orders, products, checkouts | — | Read-only webhook receiver + poll |
| **Zendesk** | Tickets, users | Tickets | Ticket creation from conversations |
| **Calendly** | Events | — | Read-only event receiver |
| **DocuSign** | Envelopes | — | Read-only envelope status receiver |
| **Jira** | Issues | Issues | Issue creation and updates (via agent tools) |

### 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

* [Connect HubSpot & Salesforce end to end](/guides/hubspot-salesforce-integration) — the full bidirectional CRM loop walkthrough.
* [Connect Shopify end to end](/guides/shopify-integration) — commerce events, cart recovery, and GDPR compliance.
* [Connect Zendesk, Calendly, DocuSign, and Jira](/guides/oauth-saas-integrations) — the shared OAuth-popup flow for four integrations.
* [Integrations API reference](/api-reference/integrations) — connect, status, sync, data, and disconnect endpoints.
* [Audit log guide](/guides/audit-log) — search, filter, and export the audit trail.
* [Connector downloads](/guides/connectors-download) — Zapier, n8n, and Make connectors.
* [Settings hub overview](/settings/overview) — the full console map for every settings surface.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.