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

# Building on PlugKit for your SaaS

> Manage your own customers' social accounts through one PlugKit account.

If your product publishes or messages on behalf of **your** customers, PlugKit
is the layer underneath: one PlugKit account, one API key on your server, and
one profile per customer.

## The model

```
Your PlugKit account ── API key (server-side only)
 ├── Profile "Customer A"  →  their Instagram, TikTok, LinkedIn…
 ├── Profile "Customer B"  →  their Facebook Page, WhatsApp…
 └── …
```

1. When a customer signs up in your app, create a profile and store its `_id`
   next to your customer record:
   ```bash theme={null}
   curl -X POST https://api.plugkit.co/v1/profiles \
     -H "Authorization: Bearer sk_your_key" -H "Content-Type: application/json" \
     -d '{ "name": "Customer A (your internal id 4812)" }'
   ```
2. Every later call names that profile (`profileId`) or one of its accounts
   (`accountId`).

> [!WARNING]
>
> **Isolation is your job.** API keys aren't scoped to a profile: every key sees
> every profile of your PlugKit account. Never expose a key to the browser, and
> always resolve `profileId` / `accountId` from your own customer record, never
> from user input.

## Connecting your customer's accounts

Two options:

**From your UI.** Call `GET /connect/{platform}?profileId=…&returnUrl=…` from
your server and send your customer to the returned `authUrl`. Once they approve,
PlugKit redirects their browser to your `returnUrl` with the result in the query
string:

```bash theme={null}
curl -G "https://api.plugkit.co/v1/connect/instagram" \
  -H "Authorization: Bearer sk_your_key" \
  --data-urlencode "profileId=PROFILE_ID" \
  --data-urlencode "returnUrl=https://app.example.com/integrations/done?customer=4812"
# → { "authUrl": "https://www.instagram.com/oauth/authorize?…" }
```

```
https://app.example.com/integrations/done?customer=4812&status=success&platform=instagram&profileId=PROFILE_ID&accountId=ACCOUNT_ID&count=1
https://app.example.com/integrations/done?customer=4812&status=error&platform=instagram&profileId=PROFILE_ID&error=Authorization+refused%3A+…&code=…
```

| Parameter | Meaning |
| - | - |
| `status` | `success` or `error`. |
| `platform` | The platform that was connected. |
| `profileId` | The profile the account landed in. |
| `accountId` | The connected account, when exactly one was connected. |
| `count` | How many accounts were connected (a Facebook login granting three Pages gives `3`, without `accountId`). |
| `error`, `code` | On `status=error`: a readable message and, when available, the API error code. |

Your existing query parameters are kept. `returnUrl` must be `https` (`http` is
accepted for `localhost`), at most 1,024 characters. PlugKit signs it in the
OAuth `state`, so it can't be swapped for another site along the way.

> [!NOTE]
>
> Treat the redirect as a signal, not as proof: anyone can open your
> `returnUrl` with made-up parameters. Confirm with `GET /accounts/{accountId}`
> (or the `account.connected` webhook) before trusting it. `returnUrl` isn't
> available for Bluesky yet. Telegram and WhatsApp numbers connected by token
> don't go through a redirect.

Without `returnUrl`, the flow ends on a PlugKit confirmation page.

**With a connect link.** `POST /connect-invites` with the `profileId` returns a
`url` valid 30 days. Send it to your customer: they pick their platforms on a
PlugKit-hosted page, and the accounts land in their profile. Good for agencies
onboarding clients by email.

```bash theme={null}
curl -X POST https://api.plugkit.co/v1/connect-invites \
  -H "Authorization: Bearer sk_your_key" -H "Content-Type: application/json" \
  -d '{ "profileId": "PROFILE_ID" }'
```

## After the connection

Each new or reconnected account fires an [`account.connected`](https://docs.plugkit.co/guides/webhooks)
webhook carrying `accountId`, `profileId` and `platform`. One authorization can
create several accounts (a Facebook login granting three Pages gives three
accounts, so three events).

Tokens can die on the platform side (password change, revoked app). The account
switches to `needsReconnection: true` and an `account.disconnected` webhook
fires with `reason: "reconnection_required"` — once, when it flips. Send the
customer back through `GET /connect/{platform}?profileId=…&accountId=…` to
reconnect the same account (its posts and conversations are kept).

## Routing webhooks

Register one [webhook](https://docs.plugkit.co/guides/webhooks.md) endpoint for your whole account.
Account events and post events carry `profileId`. Message and comment events
carry `accountId` only: keep an `accountId → profileId → your customer` map,
filled from `account.connected` and refreshed from `GET /accounts`.

## Limits to plan for

* **Rate limits are per connected account**: each of your customers' accounts
  gets its own 20 publications / messages / comment replies per minute, so one
  busy customer doesn't slow the others down. Requests that don't target an
  account (lists without `accountId`, profile management…) share your account's
  budget. Honour `retry-after`. See
  [API conventions](https://docs.plugkit.co/concepts/api-conventions.md#rate-limits).
* **Platform quotas** apply per connected account (e.g. 100 Instagram
  publications per 24 hours).
* **Plan**: Pro includes 30 connected accounts and bills extra accounts by band
  beyond that; Creator stops at 5. See [Plans & billing](https://docs.plugkit.co/concepts/billing.md).
* **Use idempotency keys** on `POST /posts` and message sends, so a retry from
  your queue never posts twice.


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