# 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.

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](/docs/monitors#monitor-a-connected-account) 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`:

```bash
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:

1. the connection's id (`con_…`);
2. its `customId`, exactly;
3. the account's handle at the provider (login, email or `@handle`), in any case;
4. its `name`, in any case.

```bash
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](/docs/monitors#monitor-a-connected-account) 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.

```bash
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](#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](#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**:

```json
{
  "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"`, with `connectionId`). Opening it again shows that it is done.
- **Expiry.** `expiresInDays` is 1 to 30 days, 7 by default. Within about a minute of `expiresAt` an unused invite is marked `expired` (a customer still in the middle of connecting gets to finish first), and a [webhook endpoint](#listen-for-connection-events) hears `connection.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 stays `expired`.
- **The link again.** `GET /v1/connections/invites` lists invites, newest first, filtered by `status` or `provider`. `url` is 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://`, or `http://localhost` and `http://127.0.0.1` while you develop (not in production). No user name or password in it, and at most 2,048 characters. A missing or invalid one answers `400 invalid_input`, with the problem in `details[0]` (`path: ["redirectUrl"]`).
- **Shown back.** The invite, the invite list and the customer's page (`GET /v1/connect/{token}`) all carry `redirectUrl`.

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 its `inviteId` and `customId` before you act on it, or rely on the `connection.connected` [event](#listen-for-connection-events).
- Invites created before `redirectUrl` was required (12 November 2026) may have none: theirs is `null`, 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.

```bash
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 in `details.capabilities`.
- Leave `capabilities` out, 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 same `customId`. 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](/docs/webhooks#webhook-endpoints) 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. |

```bash
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](/docs/webhooks#verify-the-signature) 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).
