Connecting integrations

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.

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) take pasted credentials instead. The List integrations call tells you which style each provider uses via its authKind.

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.

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.

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 }'

{
  "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.

curl https://api.sapt.ai/projects/$PROJECT_ID/connect-sessions/$TOKEN \
  -H "Authorization: ApiKey sapt_your_api_key"

{
  "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.

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`

Treat List integrations 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.

Get started

Platform

Social publishing

Analytics

REST API guides

MCP connector

Connecting integrations

1. Discover what you can connect

2. Create a connect link

3. Poll for completion

API-key integrations

OAuth provider IDs

Keep going

Integrations

REST API Reference

Authentication

​1. Discover what you can connect

​2. Create a connect link

​3. Poll for completion

​API-key integrations

​OAuth provider IDs

​Keep going

Integrations

REST API Reference

Authentication

1. Discover what you can connect

2. Create a connect link

3. Poll for completion

API-key integrations

OAuth provider IDs

Keep going