Connected accounts
Run private-data APIs as a GitHub, Google, Instagram, Cloudflare or Bing Webmaster Tools account that you, your team or your customers connect, by signing in or with a pasted key. Many accounts per provider, your own names and custom IDs, invite links for customers that send them back to your product, agent access rules with approvals, and connection events.
Last updated
On this page
- Connect an account
- Connect with a key
- Many accounts per provider
- Choose the account a call runs as
- Monitor a connected account
- Connect your customers' accounts
- Brand the connect page
- Send customers back to your product
- Ask only for what you need
- Cloudflare: everything your account allows
- Listen for connection events
- Who can manage connections
- Agent access rules
- Full access at connect time
- Approvals
- Change the rules
- Errors
- Endpoints
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. They behave the same way too: Prefer can make them answer 202 for you to poll (Durable requests), and a retry with the same Idempotency-Key returns the stored result (Idempotency).
- 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. Calls are stored like every other call: the input stays with your request history, and the result is kept for as long as your plan keeps results (24 hours on Pay as you go, 7 to 90 days on a plan: Durable requests), then deleted. Until then you can re-read it with
GET /v1/results/{id}orread_result. Disconnecting the account doesn't delete results already stored; they are deleted on the same schedule. 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.
What each provider unlocks:
| Provider | Products | Read-only? |
|---|---|---|
| Gmail, Drive, Calendar, Contacts, Search Console, Google Analytics, Google Ads, YouTube, Google Business Profile | Gmail, Drive, Calendar, Contacts and YouTube only read. Search Console and Analytics have separate read and manage capabilities. Google Ads and Business Profile have no read-only access at Google, so connecting them also allows changes. | |
| GitHub | Repositories, issues | Yes |
| Profile, posts, insights, comments | Yes | |
| Cloudflare | Zones, DNS, analytics, cache | Separate read and change capabilities |
| Bing Webmaster Tools | Search performance, crawl and indexing data, URL and sitemap submission | Separate read and manage capabilities |
YouTube revenue is its own capability (youtube_revenue_read), so a channel report never asks for revenue access. GET /v1/connections/providers lists every capability and the APIs it unlocks.
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.
Connect with a key
Cloudflare and Bing Webmaster Tools can also be connected with a key created at the provider instead of signing in. Paste it on the dashboard's connect screen or the customer's invite page, or send it from your code:
curl -sS -X POST "https://api.primaryapi.com/v1/connections/bing/api-key" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "apiKey": "'"$BING_WEBMASTER_KEY"'", "capabilities": ["webmaster_read"], "name": "Main site" }'- The key is checked with the provider first; a refused key answers
400 invalid_inputwithdetails.reason: "key_rejected"and nothing is stored. - It is stored encrypted like a sign-in token and never returned. Connecting the same provider account again updates that connection (
200); a new one answers201. capabilitieslimits what calls may use the connection for. A Cloudflare token can be limited at Cloudflare too; a Bing key can't (one key per user, for every verified site), so signing in with Microsoft is the safer choice for Bing.- Disconnecting stops PrimaryAPI using the key but doesn't delete it at the provider. Delete it there to stop access completely.
- A customer's invite page offers the key option too (
POST /v1/connect/{token}/key), with the invite's capabilities, name and custom ID.
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.
Cloudflare: everything your account allows
A Cloudflare connection asks for everything by default: zones, DNS, Workers, R2, security rules, Zero Trust and the rest of what your Cloudflare account allows. On Cloudflare's page you still choose which accounts to share, and calls reach only those.
| Capability | What it allows | APIs |
|---|---|---|
zones_read | See zones and DNS records. | cloudflare.zones, cloudflare.dns_records |
zones_manage | Add sites (zones) and see your accounts. | cloudflare.accounts, cloudflare.create_zone |
dns_manage | Create, change and delete DNS records. | cloudflare.create_dns_record, cloudflare.update_dns_record, cloudflare.delete_dns_record |
analytics_read | Traffic, cache and security analytics. | cloudflare.zone_analytics |
cache_purge | Clear cached files. | cloudflare.purge_cache |
everything | Anything the account allows. It includes every capability above. | cloudflare.api_request |
- Add a site.
cloudflare.create_zoneadds a domain to one of your accounts and returns the Cloudflare name servers to set at your registrar (nameServers). Leaveaccountout when the connection sees one account; otherwise pick one fromcloudflare.accounts. A domain that is already a zone in the account answers400 invalid_input. - Anything else.
cloudflare.api_requestcalls any endpoint of the Cloudflare API as the connected account. Sendmethod, apathsuch as/zones(relative tohttps://api.cloudflare.com/client/v4), and optionallyqueryand a JSONbody. Cloudflare's answer comes back as it is:status,success,result,result_info,errorsandmessages. It can change or delete anything the account allows, so agents should confirm with the person before any call that is not aGET. - Ask for less. Send
capabilitieswithouteverything, for example["zones_read", "dns_manage"], and only those are asked for. - Older connections. A Cloudflare account connected before 2026-11-17 keeps what it had. To use the new APIs, connect it again: the same connection gains the new capabilities.
If Cloudflare refuses one of the permissions asked for, nothing is connected and you land back with connect_error=invalid_scope. Ask for fewer capabilities, or tell us.
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.
Agent access rules
When an AI agent uses one of your accounts through PrimaryAPI's MCP server, you decide what it may do there. Each connection has its own rules, set in the dashboard (the account's page, Agent access) or with PUT /v1/connections/{id}/access.
- Only for agents on the MCP server. The rules apply to calls made through
https://api.primaryapi.com/mcp, signed in or with a key. Your API keys, OAuth apps and the REST API always have full access: they run in code you wrote. - Three rules. Allowed: the call runs. Ask: the call waits until a person approves it. Off: the call is refused with
403 connection_access_off. Neither refusal is charged. - Defaults. A rule you haven't set takes the default: APIs that only read are Allowed, APIs that change something at the provider (create a DNS record, send an email, update a campaign) are Ask.
- Per capability, then per API. Set a rule on a capability, such as Cloudflare's "Manage DNS", and every API that needs it follows. Give one API its own rule to override that. When an API needs several capabilities, the strictest rule set on them applies.
- No reconnect needed. Changing a rule takes effect on the next call. The account itself always holds the broadest access the provider offers.
Full access at connect time
Connecting asks the provider for everything it offers once, so you can loosen a rule later without signing in again. An account connected before 17 November 2026, or one where someone unticked permissions on the consent screen, has limited access: its Agent access tab says so (fullAccess: false, with the capabilities it lacks in missingCapabilities). Reconnect it once; a customer's account needs a new invite. Your rules are kept.
Approvals
When a call's rule is Ask, the MCP tool answers with the code approval_required (nothing runs, nothing is charged) and these details:
{
"approvalId": "apr_01JD…",
"approvalUrl": "https://primaryapi.com/dashboard/connections/approvals/apr_01JD…",
"expiresAt": "2026-11-18T10:00:00.000Z",
"connectionId": "con_01JD…",
"sku": "cloudflare.create_dns_record",
"source": "default",
"capability": null
}source says which rule asked: default, the API's own rule (api) or a capability's (capability, named in capability).
- The agent gives
approvalUrlto its human. The page shows who asked, the account, the API, the exact input and the reason the agent gave (itsreasonargument), marked as the agent's own words. - Someone who manages the connection chooses Approve once, Always allow this API (the API's rule becomes Allowed on this account) or Decline. Only a signed-in person can decide: never a key or an app.
- The agent runs the same call again, adding the approval's id:
{
"sku": "cloudflare.create_dns_record",
"input": { "connection": "cust_1042", "zone": "example.com", "type": "A", "name": "api", "content": "198.51.100.4" },
"approval": "apr_01JD…"
}An approval runs one call, with the same input, from the same agent, within 24 hours. A different input needs a new approval, and an approval that was declined, used or expired answers 409 approval_unavailable. Pending requests are listed on the dashboard's Connections page, and GET /v1/connection-approvals?status=pending returns them.
Change the rules
curl -sS -X PUT "https://api.primaryapi.com/v1/connections/con_01JD…/access" \
-H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "capabilities": { "dns_manage": "ask" }, "apis": { "cloudflare.delete_dns_record": "off", "cloudflare.purge_cache": null } }'capabilitiesandapishold rules (allow,askoroff). Only the rules you send change;nullremoves one, back to the default.- A capability the provider doesn't have, or an API that doesn't use this provider, answers
400 invalid_input. - The answer, like
GET /v1/connections/{id}/access, lists every capability with its rule, whether the account holds it (granted), and its APIs, each with its own rule, the rule that applies (effective) and where it comes from (source:api,capabilityordefault). - The people who manage the connection can change its rules: the member who connected it, owners and admins, and keys with
fullaccess and access to connected accounts. Every change is in the audit log.
Agents can read the rules with the MCP tool get_connection_access, and tighten them with set_connection_access. A change that loosens a rule through MCP doesn't apply: it returns an approval link for a person instead.
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. |
connection_access_off | 403 | MCP only: the agent access rule for this API is Off. details.settingsUrl is the page to change it. Not charged. |
approval_required | 403 | MCP only: the rule is Ask. A person approves the call at details.approvalUrl, then the agent runs it again with approval. Not charged. |
approval_unavailable | 409 | The approval sent was declined, already used, expired, or is for another call. Run the call without it for a new link. |
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. |
GET /v1/connections/{id}/access | The connection's agent access rules, per capability and API. |
PUT /v1/connections/{id}/access | Set or clear (null) agent access rules. |
GET /v1/connection-approvals | Agent requests (status=pending for the ones waiting). Signed-in members. |
GET /v1/connection-approvals/{id} | One request: who asked, the API, its input and the agent's reason. |
POST /v1/connection-approvals/{id}/approve | Approve it ({"always": true} also allows the API from now on). Signed-in people only. |
POST /v1/connection-approvals/{id}/decline | Decline it. Signed-in people only. |
Your request history shows which account each private-data call ran as (connection on GET /v1/requests items).