# Connecting accounts

A link your customer opens to connect their account, with no Rizamo sign-in.

## Ask for a link [#ask-for-a-link]

Your code asks for a link for one network and the profile the accounts go to (`get_connect_link` in MCP, scope `accounts:write`):

```bash
curl "https://api.rizamo.com/v1/connect/instagram?profileId=prof_...&redirectUrl=https://example.com/rizamo/done" \
  -H "Authorization: Bearer $RIZAMO_API_KEY"
```

```json
{ "url": "https://app.rizamo.com/api/connect/link/team_.../...", "expiresAt": "2026-11-03T10:30:00.000Z" }
```

Send the person to `url` within 30 minutes. It goes straight to the network, where they log in; they need no Rizamo account. It connects accounts once: a chat preview, a link checker or a second browser that opens it uses nothing up, and the first to finish connecting uses it.

- `instagram`: Instagram Login, an Instagram professional account on its own.
- `facebook`: Facebook Login, the person's Pages and the Instagram accounts linked to them. Instagram accounts connected this way can also add music to reels and get each story's final numbers when it ends; deleting Instagram posts will need it too, once Meta reviews Rizamo's access.
- `tiktok`, `threads`, `youtube`.

`redirectUrl` is any `https://` address, or `http://localhost` and `http://127.0.0.1` on any port while you develop. It is fixed in the link. Leave it out when you have no address, from a chat agent or a script: the person then lands on a Rizamo page that names the accounts connected, or says why not, and tells them to go back to their agent or close the tab. The MCP tool takes no `redirectUrl`: agents always send people to that page.

## What the person sees [#what-the-person-sees]

A login that reaches one new account connects it at once. One that reaches several, such as Pages or YouTube channels, or an account your team already has, shows a short page to pick them, with only new accounts ticked. It shows no prices and nothing of your team. An account already connected in a profile your key does not reach cannot be picked.

## Back at your address [#back-at-your-address]

When you gave a `redirectUrl`, Rizamo adds these parameters to it, and nothing else:

| Parameter | Value |
| --- | --- |
| `status` | `connected` or `error` |
| `network` | the network you asked for |
| `profileId` | the profile you named |
| `accountIds` | the accounts connected, comma-separated |
| `billing` | each one's billing state, in the same order: `active` or `awaiting_payment` |
| `error` | `cancelled`, `refused`, `no_accounts`, `expired`, `used`, `unavailable`, `forbidden`, `gone` or `failed` |
| `message` | what went wrong, in plain words |

None of them works without your key: read each account with `GET /v1/accounts/{id}`. A return can arrive more than once, when the person reloads it, so take `GET /v1/accounts` (`list_accounts` in MCP) as the truth. A link opened once it is used or expired, or after your key lost access, stays on a Rizamo page that says why: only a person back from the network comes to your address. Webhook endpoints that take `account.connected` get one per account.

## Billing [#billing]

Accounts you add are billed as in the web app, the first 2 free. On the free plan, the rest arrive `awaiting_payment` until a team owner starts a plan. On a paid plan they are charged at once to the card on file: your call is the consent. A charge that needs the card holder leaves them `awaiting_payment` until an owner pays in the web app. There is no limit on how many you add: a team owner can set one in the web app (Plan & usage), and none is set until they do. Beyond it, accounts arrive `awaiting_payment` until an owner pays. `GET /v1/billing` shows the plan and that limit (`apiCap`, null while there is none).

## Log in again [#log-in-again]

When an account needs a new login, ask for a link with its `connectionId` and its network. Only that login's accounts are updated: another account of your team the person also manages stays on its own login.

## Remove an account [#remove-an-account]

`GET /v1/accounts/{id}/removal` (`get_account_removal` in MCP) counts what removing it does to its posts: the scheduled, draft, published and failed posts that use it, and how many go to it alone. Show the person those counts, then `DELETE /v1/accounts/{id}` (`remove_account` in MCP) removes it and answers the same counts.

- Posts that go to it alone move to Deleted, where they can be restored for 30 days. Posts with other accounts keep its part that went out, with its link, and lose the part that did not.
- Its comments and messages in the inbox go at once.
- Nothing changes on the network.
- Only an owner, an owner's agent, or an API key an owner let remove accounts (Developers in the web app) may. Anyone else gets `403`.
- Connecting the same account again brings it back with the same id.