Skip to main content
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

  1. When a customer signs up in your app, create a profile and store its _id next to your customer record:
  2. Every later call names that profile (profileId) or one of its accounts (accountId).
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:
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.
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.

After the connection

Each new or reconnected account fires an account.connected 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 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.
  • 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.
  • Use idempotency keys on POST /posts and message sends, so a retry from your queue never posts twice.