# Connect platform accounts (https://upapi.io/docs/connect-platforms)



Some operations act as an account on another platform: following on TikTok, commenting on Reddit,
reading a LinkedIn profile as a logged-in member. They need that account's login session. Your
agent can walk you through handing upAPI the session once, so it is saved to your workspace
instead of travelling in every request.

## Connect an account [#connect-an-account]

Ask your agent: "Connect my TikTok account". It calls `connect_platform`, which returns a one-time
link and the exact steps.

1. Open the link in the browser where you are signed in to upAPI. It works once and for 15 minutes.
2. On the page, open the platform's login (it opens in a new tab) and sign in to the account you
   want to connect.
3. In that tab, press F12, open **Network**, reload, click any request to the platform, and copy the
   value of the **Cookie** request header. The page lists the cookie names it needs.
4. Back on the upAPI page, paste it, type the account handle, tick the box accepting the risk warning, and press **Connect**.
5. Tell your agent you are done. It calls `check_platform_account` to confirm.

The page opens with a **Connect at your own risk** warning, and **Connect** stays disabled until you tick the box accepting it: upAPI is not liable for a leaked session, a suspended account or other consequences of connecting, and you are responsible for the platform's terms. The details are in the [Privacy Policy](https://upapi.io/privacy#connected-platforms) and the [Terms](https://upapi.io/terms#connected-platforms).

upAPI checks the session before saving it where the platform has a reliable check. If the platform
rejects it, nothing is saved, an account you already connected stays as it was, and you can paste
again with the same link. That check is a metered operation, so a rejected paste still uses units.

Paste the cookies into that page only. Never paste them into the chat with your agent: a chat
transcript is stored by your AI client, and the tools never ask for them.

A browser extension that captures the session in one click is planned. Until it ships, copying the
header by hand is the only way.

## Platforms [#platforms]

| Platform  | Can be connected | Session check                                              |
| --------- | ---------------- | ---------------------------------------------------------- |
| TikTok    | Yes              | None that proves the session is alive: saved, not verified |
| Instagram | Yes              | Not callable yet: saved, not verified                      |
| LinkedIn  | Yes              | Yes                                                        |
| Reddit    | Yes              | Yes                                                        |
| X         | Yes              | Needs a pinned proxy: saved, not verified                  |
| Facebook  | Yes              | None that proves the session is alive: saved, not verified |
| Contra    | Not yet          | Its cookies have not been measured                         |
| Wellfound | Not yet          | Its session format has not been measured                   |

Your agent sees the platforms it can connect in the `platform` choices of `connect_platform`, and asking for one that cannot be connected yet explains why. "Saved, not verified" means upAPI stored the session but has no reliable way to tell whether the platform still accepts it.

## Use the saved session [#use-the-saved-session]

Once an account is connected you can call the operations that need it without the session field.
Leave out `sessionCookies` (or `auth_token` and `ct0` for X) and the gateway fills them from
the stored session for your workspace. This works through your MCP agent and the dashboard try-it
page. It does not work for API keys yet: a key must still send the session itself.

* **Your value wins.** If you send the field, the stored session is not touched. An empty string
  counts as left out.
* **Only operations that cannot run without a session.** Public reads that take an optional
  session stay anonymous unless you send one.
* **Nothing connected is an answer, not a dead end.** Calling one of these operations with no
  session and no connected account (or an expired one) answers `401 AUTH_EXPIRED` with "No account
  is connected" or "session has expired", free of charge. Your agent gets `next` pointing at
  `connect_platform`.
* **One account per platform.** With several connected accounts for one platform the call is
  refused with `INVALID_INPUT` and the account names. Send the session yourself, or disconnect
  the others.
* **It stays inside upAPI.** Platforms rotate cookies as you use them. upAPI keeps the new ones and
  removes them from the response, so the operation's answer never contains your session. A call
  that sent its own session gets that session's refreshed cookies back as before. Calls that used a
  saved session are never served from, or written to, the response cache.
* **A rejected session is not charged, and not always expired.** If the platform rejects the saved
  session the call is free. The connection is marked expired, and the error carries `reconnect`
  (`{ platform, tool: "connect_platform", path }`), only when the platform's own check agrees the
  session is dead, or when it happens twice within 15 minutes. One rejection can also mean the
  exit address was blocked, so a single failure keeps the connection and returns the operation's
  own error.

Contra and Wellfound operations are wired to the same lookup, and start using it once those
platforms can be connected.

## What upAPI stores [#what-upapi-stores]

* Only the cookies the platform needs. Everything else in your paste is dropped in your browser
  before anything is sent, and dropped again on the server.
* The cookies are encrypted at rest. No tool and no page shows them again: a connected account is
  listed by platform, handle, status, the cookie **names** it holds, and timestamps.
* Who connected it and when.

Platforms often tie a session to the network and browser that created it. A session replayed from
another address can be logged out by the platform. If an operation reports an expired session, run
the connect steps again.

## Who can do what [#who-can-do-what]

* Connecting and disconnecting need an OAuth sign-in with the **Connected services** permission and
  the admin or owner role. An API key is refused for both, so a leaked key cannot plant a session in
  your workspace or remove one.
* Listing accounts shows the redacted view to any workspace member whose connection holds the
  permission.
* Using a saved session in a call needs the **Connected services** permission on an MCP connection.
  API keys cannot use a saved session yet, and cannot connect or disconnect one either.
* Checking an account needs the same role. It runs the platform's check operation once, metered
  like any operation.

## Disconnect [#disconnect]

Ask your agent to disconnect the account. `disconnect_platform_account` asks for a confirmation,
then deletes the stored session. To end the session on the platform too, log out of that platform
everywhere.

## Tools [#tools]

| Tool                          | What it does                                              |
| ----------------------------- | --------------------------------------------------------- |
| `connect_platform`            | Returns the one-time link and the steps.                  |
| `list_platform_accounts`      | Connected accounts: platform, handle, status, last check. |
| `check_platform_account`      | Re-checks one account and updates its status.             |
| `disconnect_platform_account` | Deletes the stored session. Needs a confirmation.         |

The full list of account tools is on [MCP tools](https://upapi.io/docs/mcp-tools).