Connected accounts
Run private-data APIs as a GitHub, Google, Instagram or Cloudflare account that you, your team or your customers connect. Many accounts per provider, your own names and custom IDs, invite links for customers that send them back to your product, and connection events.
Last updated
On this page
Some APIs read private data: your repositories (github.my_repos), your email (gmail.search), your Instagram insights (instagram.media_insights). They run as an account someone connected to your workspace, with the same key, envelope and credits as every other API.
- Who connects. A person signs in at the provider and approves what will be shared. That can be you, a teammate, or one of your customers through an invite link.
- What is kept. The account's tokens are stored encrypted and never returned by any endpoint. Results of private-data APIs are never stored: they reach you once, in the response. A monitor keeps its webhook event encrypted only until it is delivered.
- What it costs. A call costs its listed price in credits. Calls that fail because no account can serve them (
connection_required,connection_needs_reauth) are never charged.
Instagram accepts business and creator (professional) accounts only. On Cloudflare, the consent screen asks which of your Cloudflare accounts to share, and calls reach only those.
Connect an account
In the dashboard, open Connections and choose Connect an account under the provider. You can give the account a name and a custom ID right away (both optional, see below).
An agent without a dashboard asks for a link instead. POST /v1/connections/{provider}/link returns a short-lived url for a member of your workspace to open. A call to a private-data API that finds no account answers 403 connection_required with the same kind of link in details.connectUrl.
To connect a second account of the same provider from the same browser, connect again. Google and GitHub ask which account to use; Instagram asks you to sign in again.
Many accounts per provider
A workspace can connect as many accounts of a provider as it needs, for example one Instagram account per client of an agency. Two fields tell them apart:
name: your name for the account, such as "Acme Bakery". Up to 80 characters.customId: your own reference, such as your customer's id in your database. Up to 128 letters, digits and. _ - : / @. It is unique in your workspace among connections that are not disconnected.
Set or change both later, or clear them with null:
curl -sS -X PATCH "https://api.primaryapi.com/v1/connections/con_01JD…" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Acme Bakery", "customId": "cust_1042" }'A customId another connection already uses answers 409 custom_id_taken, with that connection's id in details.connectionId.
Find connections with GET /v1/connections, filtered by provider, customId, status or q (a search of name, custom ID and handle). Disconnected accounts are listed only with status=revoked. GET /v1/connections/by-custom-id/{customId} returns the one connection with that custom ID.
Choose the account a call runs as
Every private-data API takes an optional connection input. It is matched in this order:
- the connection's id (
con_…); - its
customId, exactly; - the account's handle at the provider (login, email or
@handle), in any case; - its
name, in any case.
curl -sS -X POST "https://api.primaryapi.com/v1/run/instagram.my_profile" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "connection": "cust_1042" }'Prefer the customId or the id: a handle or a name can match two accounts, and then the call answers 400 invalid_input with the candidates in details.connections (id, label, name, customId, status). The same happens when you leave connection out and several accounts could serve the call. From the dashboard, your own single account is used.
Monitor a connected account
A monitor runs a private-data API on a schedule and sends the result to your webhook. Each monitor reads one account, chosen with connection when you create it and kept by its id, so renaming the account or changing its custom ID doesn't affect it. Disconnecting the account deletes its monitors, paused ones too, and reconnecting doesn't bring them back. GET /v1/monitors?connectionId={id} lists them before you disconnect. A member leaving the workspace doesn't affect the accounts they connected or their monitors.
Connect your customers' accounts
An invite is a link you give to someone outside your workspace, usually a customer, so they can connect their own account. They need no PrimaryAPI account and never see your dashboard.
PrimaryAPI never emails or otherwise contacts your customers. An invite is only a link: you share it however you like, or build it into your own product.
curl -sS -X POST "https://api.primaryapi.com/v1/connections/instagram/invites" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "redirectUrl": "https://app.example.com/settings/integrations", "name": "Acme Bakery", "customId": "cust_1042", "capabilities": ["insights"], "expiresInDays": 7 }'| Parameter | Required | What it is |
|---|---|---|
redirectUrl | Yes | Where your customer lands after connecting, usually a page in your product, such as the integrations page they started from. We add the result to it: Send customers back to your product. |
name | No | Who the invite is for. Your customer sees it on the page ("for Acme Bakery"), and the connection gets it. |
customId | No | Your own reference, such as your customer's ID. The connection gets it; your customer never sees it. |
capabilities | No | What to ask for. Leave it out, or send [], to ask for everything. profile is always included: Ask only for what you need. |
expiresInDays | No | 1 to 30. 7 by default. |
Send redirectUrl with every invite. There is no workspace default, and nothing is carried over from an earlier invite. Without it the request answers 400 invalid_input, with details[0].path set to ["redirectUrl"].
201 Created:
{
"id": "cin_01JD…",
"provider": "instagram",
"capabilities": ["profile", "insights"],
"name": "Acme Bakery",
"customId": "cust_1042",
"status": "pending",
"url": "https://pluginconnector.com/c/…",
"redirectUrl": "https://app.example.com/settings/integrations",
"createdByUserId": null,
"createdByName": "backend",
"createdAt": "2026-11-12T10:00:00.000Z",
"expiresAt": "2026-11-19T10:00:00.000Z",
"connectedAt": null,
"connectionId": null
}Share url with your customer yourself: in your own email, a chat, or a page of your app. When they open it they see:
- your workspace's name and the provider;
- what will be shared, capability by capability;
- the invite's name, so they know it is meant for them;
- a button to continue to the provider, where they sign in and approve.
They never see your custom ID, your other connections or anything else about your workspace. They can remove the access at any time from their account settings at the provider.
When they finish, the account appears in your workspace with the invite's name and customId and connectedVia: "invite", and their page sends them to your redirectUrl. From then on, run calls with "connection": "cust_1042".
- Single use. The first account connected through the link uses it up (
status: "connected", withconnectionId). Opening it again shows that it is done. - Expiry.
expiresInDaysis 1 to 30 days, 7 by default. Within about a minute ofexpiresAtan unused invite is markedexpired(a customer still in the middle of connecting gets to finish first), and a webhook endpoint hearsconnection.invite_expired. Send a new invite when one expires. - Cancel.
DELETE /v1/connections/invites/{id}stops a pending link from working. An invite that has already expired staysexpired. - The link again.
GET /v1/connections/inviteslists invites, newest first, filtered bystatusorprovider.urlis included while an invite is pending, for callers who can manage connections. - Same account twice. If the customer connects an account your workspace already has, that connection is updated: fresh access, and the invite's name and custom ID, unless the custom ID belongs to another connection.
- Reconnecting. A disconnected account that is connected again keeps its custom ID, unless another connection took it in the meantime. Then the custom ID is cleared, and the change is recorded in your workspace's audit log.
Brand the connect page
Your customers open invite links on pluginconnector.com, a neutral page with the Plugin Connector logo at the top and your workspace's name on the card. You can give the card your own look: in the dashboard, open Settings › Connect page.
- Logo. A square PNG, JPEG, WebP or SVG, up to 256 KB. Without one, the page shows your workspace's initial.
- Button. The color of the button that continues to the provider. It also colors the checkmarks and the initial.
- Button text. The color of the button's label. If it would be hard to read on your button color, the page uses black or white text instead, and the dashboard tells you so as you pick it.
- Background. The color behind the card.
Leave a color empty to use PrimaryAPI's style for it. The preview next to the form shows your changes before you save them, and Reset to PrimaryAPI style removes your logo and colors. Changes apply to every link, including ones you already sent, the next time a customer opens one. Owners and admins can change the connect page; every member can see it.
Send customers back to your product
Every invite's redirectUrl is a page in your own product. When your customer is done, their page sends them there, for example back to the integrations page they started from. Your URL can carry its own query, such as https://app.example.com/settings/integrations?tab=instagram.
- Rules. Required.
https://, orhttp://localhostandhttp://127.0.0.1while you develop (not in production). No user name or password in it, and at most 2,048 characters. A missing or invalid one answers400 invalid_input, with the problem indetails[0](path: ["redirectUrl"]). - Shown back. The invite, the invite list and the customer's page (
GET /v1/connect/{token}) all carryredirectUrl.
When the customer is done, their page adds these query parameters to your URL. Your URL's own query parameters and #fragment are kept; ours replace any of the same name.
| Outcome | What the page does | Parameters added |
|---|---|---|
| Connected | Says so briefly, then sends them to your URL, with a "Continue" link at once | status=connected&connection_id=con_…&invite_id=cin_… |
| Something went wrong at the provider (they declined, or the sign-in failed) | Shows the error with a "Try again" button and a "Return to" link, then sends them back after a few seconds | status=error&error=<code>&invite_id=cin_… |
| The link was already used, has expired or was cancelled | Shows that, with a "Return to" link only (no automatic redirect) | status=error&error=invite_unavailable&invite_id=cin_… |
error is a short code, such as access_denied when the customer declined at the provider.
- Your custom ID is never added. It is your own reference and would show in your customer's address bar. If you need your own state, put it in the URL itself:
https://app.example.com/integrations?account=1042. - Don't trust the parameters alone. Anyone can type a URL. Read the connection (
GET /v1/connections/{connection_id}) and check itsinviteIdandcustomIdbefore you act on it, or rely on theconnection.connectedevent. - Invites created before
redirectUrlwas required (12 November 2026) may have none: theirs isnull, and their customers see "Connected. You can close this window." instead.
The customer's page reads GET /v1/connect/{token}, which also has inviteId, redirectUrl and connectionId. connectionId is set once the invite is connected; it stays null on an older invite without a redirectUrl, so that page learns nothing about your connection.
Ask only for what you need
An invite doesn't have to ask for everything the provider offers. List the capabilities your calls need in capabilities, and your customer is asked for those and nothing else. GET /v1/connections/providers lists each provider's capabilities and the APIs they unlock.
curl -sS -X POST "https://api.primaryapi.com/v1/connections/google/invites" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "redirectUrl": "https://app.example.com/settings/integrations", "name": "Orchard Accounting", "customId": "cust_1170", "capabilities": ["calendar_read"] }'profile(who the account is) is always included, so this invite asks for["profile", "calendar_read"].- A capability the provider doesn't have answers
400 invalid_input, with the provider's capabilities indetails.capabilities. - Leave
capabilitiesout, or send[], to ask for everything. - Calls can use the account only for what the invite asked for and the customer allowed. Calls that need more answer
403 connection_required, naming the account and the missing capability (details.missingCapabilities). Nothing is charged. - To ask for more later, send a new invite with the full list, for example
["calendar_read", "gmail_read"], and the samecustomId. When the customer connects the same account through it, that connection gains what they allowed.
POST /v1/connections/{provider}/start and /link take capabilities in the same way.
Listen for connection events
A webhook endpoint tells your product when something happens to your workspace's connected accounts, so you don't have to poll:
| Event | When |
|---|---|
connection.connected | An account was connected by a member, through a connect link or by a customer through an invite. data.reconnected is true for an account you had before, and data.invite names the invite it came through. |
connection.needs_reauth | An account must be reconnected: its access expired or was revoked at the provider. Sent once, when it changes. |
connection.disconnected | An account was disconnected. data.deletedMonitorIds lists the monitors deleted with it. |
connection.invite_expired | An invite expired unused. |
curl -sS -X POST "https://api.primaryapi.com/v1/webhook-endpoints" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://app.example.com/hooks/primaryapi", "events": ["connection.connected", "connection.needs_reauth"] }'Every event carries the account's customId (and the invite's), so you can match it to your customer's record. Events never carry tokens or anything read from the account. They are signed with your workspace's webhook secret: Webhooks shows how to check them.
Who can manage connections
| Caller | Read (GET) | Connect, invite, rename, disconnect |
|---|---|---|
| Owners and admins | Yes | Yes, any connection |
| Developers | Yes | Yes; they disconnect only the accounts they connected or invited |
| Billing and viewer members | Yes | No |
API key with full access and access to connected accounts | Yes | Invites, rename, disconnect (a key cannot connect in a browser) |
API key with run access and access to connected accounts | Yes | Connect links only |
API key with view access | Yes | No |
An owner or admin gives a key access to connected accounts in the dashboard (Keys › Connected accounts). Keys have no access by default, and agent trial keys can never have it.
Errors
| Code | Status | When |
|---|---|---|
connection_required | 403 | No account of the workspace can run this API (none connected, or none with the right capability). details.connectUrl is a link to connect one. When one account is in question, details names it, and missingCapabilities lists what it wasn't given. Not charged. |
connection_needs_reauth | 403 | The account must be connected again: its access expired or was removed. details names the connection (connectionId, label, name, customId). Not charged. |
invalid_input | 400 | connection matches no account, or matches two. details.connections lists the candidates. Also an invite without a valid redirectUrl (details[0].path is ["redirectUrl"]). |
custom_id_taken | 409 | Another connection already uses this customId. |
invite_unavailable | 410 | The invite link was used, expired or was cancelled. Create a new invite. |
Endpoints
| Method and path | What it does |
|---|---|
GET /v1/connections | List connections (provider, customId, q, status). |
GET /v1/connections/{id} | One connection. |
GET /v1/connections/by-custom-id/{customId} | The connection with your custom ID (URL-encode it). |
PATCH /v1/connections/{id} | Set or clear name and customId. |
DELETE /v1/connections/{id} | Disconnect the account. |
POST /v1/connections/{provider}/link | A short-lived link for a member of your workspace to connect an account. |
POST /v1/connections/{provider}/invites | An invite link for a customer (redirectUrl, required; name, customId, capabilities, expiresInDays). |
GET /v1/connections/invites | List invites (status, provider). |
DELETE /v1/connections/invites/{id} | Cancel a pending invite. |
GET /v1/connections/providers | Providers and what each capability unlocks. No key needed. |
Your request history shows which account each private-data call ran as (connection on GET /v1/requests items).