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

# Connecting integrations

> Programmatically generate an OAuth connect link for Meta, Gmail, Google Business Profile, and more — and hand it to your client during onboarding.

Everything you can connect from the Sapt dashboard, you can also connect over the REST API. This is what you reach for when you onboard clients through your own app or funnel: you ask Sapt for a secure connect link for a provider like Meta, hand that link to your client, and poll until they finish signing in.

The flow is the same for every OAuth provider — only the `providerId` changes.

<Note>
  There are two connection styles. **OAuth providers** (Meta, Gmail, Google Business Profile, …) use the connect-session flow below. **API-key providers** (see [API-key integrations](#api-key-integrations)) take pasted credentials instead. The [List integrations](#1-discover-what-you-can-connect) call tells you which style each provider uses via its `authKind`.
</Note>

## 1. Discover what you can connect

Call **List integrations** to see every provider available to a Project and its current connection status. This is the authoritative source for the `providerId` values and each provider's `authKind`.

```bash theme={null}
curl https://api.sapt.ai/projects/$PROJECT_ID/integrations \
  -H "Authorization: ApiKey sapt_your_api_key"
```

Each entry includes the fields you need to drive a connect UI:

| Field               | What it tells you                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `providerId`        | The id you pass when connecting — e.g. `meta`.                                              |
| `displayName`       | Human label, e.g. "Meta".                                                                   |
| `authKind`          | `oauth2` (use connect-sessions) or `api_key` (submit credentials).                          |
| `connected`         | Whether this Project already has the integration connected.                                 |
| `connectedAccounts` | For multi-account providers, the sub-accounts already linked (Pages, mailboxes, locations). |

## 2. Create a connect link

For any `oauth2` provider, mint a one-time connect link with **Create a connect session**. Pass the `providerId` from step 1.

```bash theme={null}
curl -X POST https://api.sapt.ai/projects/$PROJECT_ID/connect-sessions \
  -H "Authorization: ApiKey sapt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "providerId": "meta", "clientInvite": true }'
```

```json theme={null}
{
  "connectUrl": "https://api.sapt.ai/integrations/oauth/meta/start/abc123…",
  "token": "abc123…",
  "expiresAt": "2026-06-24T12:00:00.000Z"
}
```

* **`connectUrl`** is the link you give your client. Opening it begins the OAuth consent flow and, on completion, lands them on a Sapt-hosted result page.
* **`token`** identifies this session — use it to poll for completion in step 3.
* **`clientInvite: true`** extends the link's lifetime so it survives being emailed or embedded in an onboarding step, rather than expiring in minutes. Omit it for short-lived, same-session connects.

## 3. Poll for completion

The connect link finishes on Sapt's side, not yours — so poll **Get connect session status** with the `token` until it leaves `pending`.

```bash theme={null}
curl https://api.sapt.ai/projects/$PROJECT_ID/connect-sessions/$TOKEN \
  -H "Authorization: ApiKey sapt_your_api_key"
```

```json theme={null}
{
  "token": "abc123…",
  "providerId": "meta",
  "status": "completed",
  "expiresAt": "2026-06-24T12:00:00.000Z",
  "completedAt": "2026-06-24T11:42:10.000Z",
  "error": null
}
```

| `status`    | Meaning                                                                        |
| ----------- | ------------------------------------------------------------------------------ |
| `pending`   | The client hasn't finished consent yet. Keep polling.                          |
| `completed` | Connected. The provider's tools are now live for the Project.                  |
| `failed`    | The client started but consent failed — see `error`. Mint a new link to retry. |
| `expired`   | The link's TTL elapsed before completion. Mint a new link.                     |

## API-key integrations

Providers whose `authKind` is `api_key` (for example Stripe or Shopify) don't use a connect link — you submit their credentials directly with **Connect an API-key integration**. OAuth providers reject this call, so always branch on `authKind` from step 1.

```bash theme={null}
curl -X POST https://api.sapt.ai/projects/$PROJECT_ID/integrations \
  -H "Authorization: ApiKey sapt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "providerId": "some_provider", "credentials": { "apiKey": "…" } }'
```

## OAuth provider IDs

The most-requested OAuth providers and their exact ids — note the mix of hyphens and underscores:

| Provider                    | `providerId`       |
| --------------------------- | ------------------ |
| Meta (Facebook + Instagram) | `meta`             |
| Gmail                       | `gmail`            |
| Google Business Profile     | `google-business`  |
| Google Ads                  | `google-ads`       |
| Google Analytics            | `google_analytics` |
| Google Calendar             | `google_calendar`  |

<Warning>
  Treat [List integrations](#1-discover-what-you-can-connect) as the source of truth for `providerId` values and `authKind`. The set of providers and their availability depend on the Project, and ids are case- and separator-sensitive.
</Warning>

## Keep going

<CardGroup cols={2}>
  <Card title="Integrations" href="/docs/mintlify/platform/integrations" description="What connecting each tool unlocks." />

  <Card title="REST API Reference" href="/docs/mintlify/api/overview" description="Full endpoint reference for connect-sessions and integrations." />

  <Card title="Authentication" href="/docs/mintlify/guides/authentication" description="API keys, OAuth scopes, and refresh tokens." />
</CardGroup>