# Connecting an application to smoooch (OAuth)

This is for the people — and the AI agents — who build an application of ours that connects to smoooch. It says how a person connects their smoooch workspace to the application, what the application can do afterwards, and how it gives that workspace a smoooch plan.

In short:

1. An owner of smoooch.bio makes an **application** on the owner site and gets a **client ID** and a **client secret**. Both go into the application's admin settings.
2. A person clicks "Connect smoooch" in the application. They land on smoooch, choose **one workspace** and press Connect.
3. The application's server swaps the code it gets back for an **access token** and a **refresh token**.
4. With the access token the application uses the [REST API](/docs/api) for that workspace — reading and writing — and can **set the workspace's plan and limits**.

Everything here is standard OAuth 2.0 (authorization code, PKCE supported). Base address: `https://smoooch.bio`. The same facts as JSON are at `/.well-known/oauth-authorization-server`.

## Setting it up

### On smoooch (an owner, once)

Owner site → **Apps** → **New application**:

- **Name** — what people see on the connect screen: `Your app`.
- **Redirect addresses** — where smoooch may send people back to, one per line. `https://` only (`http://localhost` is allowed for development). The address must match **exactly**, character for character.
- **May set the plan and limits** — leave on for your app.

You get three values. The secret is shown **once**; smoooch keeps only a fingerprint of it.

| Value | Looks like | Goes into your app as |
| --- | --- | --- |
| Client ID | `sbc_…` | `SMOOOCH_CLIENT_ID` |
| Client secret | `sbs_…` | `SMOOOCH_CLIENT_SECRET` |
| smoooch address | `https://smoooch.bio` | `SMOOOCH_BASE_URL` |

A lost secret cannot be read again: use **New secret** on the same page. The old one stops working at once; connections stay.

### In your app (what to build)

An admin settings screen with:

- fields for the three values above (the secret stored encrypted, never sent to a browser again);
- the **redirect address** your app uses, shown so it can be copied into smoooch (for example `https://app.example.com/integrations/smoooch/callback`);
- **what a connected workspace gets**: a plan (`free`, `pro` or `agency`) and, if wanted, limits (see [The plan a connection gives](#the-plan-a-connection-gives)). This is your app's own setting — per your app plan, per customer, however your app wants. smoooch only does what your app tells it for each connection.

Per account in your app (or organization), store for each connection: `connection_id`, `workspace.id`, `workspace.name`, the refresh token (encrypted), the access token and when it runs out.

## The flow

### 1. Send the person to smoooch

```
GET https://smoooch.bio/oauth/authorize
  ?response_type=code
  &client_id=sbc_…
  &redirect_uri=https://app.example.com/integrations/smoooch/callback
  &state=<random, kept in the person's session in your app>
  &code_challenge=<base64url(sha256(code_verifier))>
  &code_challenge_method=S256
```

- `state` is required in practice: check it when the person comes back, to know the answer belongs to the request you started.
- `code_challenge` (PKCE) is optional but recommended. Only `S256`.
- There are no scopes to choose. A connection always means the same thing: **full access to the one workspace** the person picks — read everything, create, change and delete links, set its plan.

The person signs in to smoooch if they are not, sees what your app will be able to do, chooses a workspace and presses **Connect**. Only an **owner** of a workspace can connect it.

### 2. They come back

```
https://app.example.com/integrations/smoooch/callback?code=sb_oac_…&state=…
```

or, if they pressed Cancel:

```
…/callback?error=access_denied&state=…
```

The code works **once** and for **five minutes**.

### 3. Swap the code for tokens (server to server)

```bash
curl -X POST https://smoooch.bio/oauth/token \
  -u "$SMOOOCH_CLIENT_ID:$SMOOOCH_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=sb_oac_… \
  -d redirect_uri=https://app.example.com/integrations/smoooch/callback \
  -d code_verifier=<the verifier, if you sent a code_challenge>
```

The client proves itself with HTTP Basic (as above) or with `client_id` and `client_secret` in the body. The body may be form-encoded or JSON.

```json
{
  "access_token": "sb_oat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "sb_ort_…",
  "scope": "workspace",
  "connection_id": 12,
  "workspace": { "id": 7, "name": "Nova Agency" }
}
```

- The **access token** lasts one hour.
- The **refresh token** does not run out. It stays the same when you use it; keep it encrypted.
- One application has **one connection per workspace**. Connecting the same workspace again replaces the earlier connection: its tokens stop working, the plan it gave carries over.
- A person can connect several workspaces: one flow each, one connection each.

### 4. A new access token

```bash
curl -X POST https://smoooch.bio/oauth/token \
  -u "$SMOOOCH_CLIENT_ID:$SMOOOCH_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=sb_ort_…
```

Same answer as above, with a new `access_token`. Do this when the old one is about to run out, or when a call answers `401` with `"code": "invalid_token"`.

If this answers `400 invalid_grant`, the connection is gone — the person disconnected your app in smoooch, or an owner did. Mark it as disconnected on your side and offer "Connect" again.

### 5. Ending a connection

From your app, when the person disconnects there or their account with you ends:

```bash
curl -X POST https://smoooch.bio/oauth/revoke \
  -u "$SMOOOCH_CLIENT_ID:$SMOOOCH_CLIENT_SECRET" \
  -d token=sb_ort_…        # the refresh token or an access token
```

Always answers `200`. The tokens stop working and **the plan your app gave ends at once**; the workspace falls back to what it pays for itself (or Free). Nothing in the workspace is deleted. `DELETE /api/v1/connection` with the access token does the same.

From smoooch, the person can disconnect under Settings → Workspace → Connected apps. Your app notices at its next call (`401`) or refresh (`invalid_grant`).

### Errors from `/oauth/token`

JSON, as the standard says: `{ "error": "…", "error_description": "…" }`.

| Status | `error` | Meaning |
| --- | --- | --- |
| 401 | `invalid_client` | Unknown client ID or wrong secret |
| 400 | `invalid_grant` | Code wrong, used, older than five minutes, or for another redirect address; PKCE verifier wrong; refresh token wrong or connection ended |
| 400 | `unsupported_grant_type` | `grant_type` is not `authorization_code` or `refresh_token` |

If the client ID or the redirect address in step 1 is wrong, the person sees a message on smoooch and is **not** sent back — smoooch never sends anyone to an address that is not on the application's list.

## Using the access token

```
Authorization: Bearer sb_oat_…
```

It works on every endpoint of the [REST API](/docs/api) — `https://smoooch.bio/api/v1/…` — for the connected workspace, **reading and writing, whatever plan the workspace is on**. Server to server only: never put a token in a browser or an app.

What that covers today:

| What | Endpoints |
| --- | --- |
| The workspace, its plan, limits and how much is used | `GET /workspace` |
| Landing pages: list, one page with its buttons and socials, stats | `GET /pages`, `GET /pages/:id`, `GET /pages/:id/stats`, `GET /items/:id/stats` |
| Direct links: list, read, **create, change, delete**, stats | `GET/POST /direct-links`, `GET/PATCH/DELETE /direct-links/:id`, `GET /direct-links/:id/stats` |
| Is an address free? | `GET /names/:name` |
| Groups (a model, a creator, a client): list, **create, rename, delete** | `GET/POST /groups`, `PATCH/DELETE /groups/:id` |
| Which group a link is in | `groupId` on a direct link (`POST`/`PATCH`); `PATCH /pages/:id` with `{ "groupId": 3 }` or `null` |
| All stats of the workspace, and live numbers | `GET /stats`, `GET /live` |
| The connection itself, and the plan it gives | `GET /connection`, `PUT/DELETE /connection/grant`, `DELETE /connection` |

Landing pages are made and designed in smoooch itself; over the API they can be read, put into a group and measured. Direct links can be fully managed over the API.

### After connecting: fetch everything

```bash
A="Authorization: Bearer $ACCESS_TOKEN"
curl -H "$A" https://smoooch.bio/api/v1/connection      # who connected, plan, limits, usage
curl -H "$A" https://smoooch.bio/api/v1/groups          # { data: [{ id, name }] }
curl -H "$A" https://smoooch.bio/api/v1/pages           # landing pages, each with groupId
curl -H "$A" https://smoooch.bio/api/v1/direct-links    # direct links, each with groupId
```

Every page and direct link has a stable numeric `id`, its public `url` and a `groupId` (or `null`).

### One workspace, many models

A workspace often holds the links of several models or creators. Two ways to say which link belongs to whom, and they work together:

- **In your app**: keep your own table — your model → smoooch page ids and direct link ids. Ids never change, also when a link is renamed.
- **In smoooch, with groups**: a link is in one group or none. Make a group per model (`POST /groups { "name": "Nova" }`), put links into it (`groupId`), and the person sees the same grouping on their Links and Stats pages in smoooch. Reading `groupId` back gives your app a first guess at who owns which link.

### What the links earn (Fanvue)

If the person has connected Fanvue in smoooch (Revenue in the app), the same access token reads what their links earned — per link, source, country, device and kind of payment, in USD cents:

```bash
curl -H "$A" "https://smoooch.bio/api/v1/revenue?days=30"            # or ?from=2026-10-01&to=2026-10-31
curl -H "$A" "https://smoooch.bio/api/v1/revenue?directLinkId=12"    # one link
curl -H "$A" https://smoooch.bio/api/v1/revenue/accounts            # which Fanvue creators are connected
```

`links[]` carries each link's `id` and `groupId`, so revenue joins straight onto your app's own table of models and links. The fields are described in the [API reference](/docs/api) under "Revenue (Fanvue)". Nothing is connected: `/revenue/accounts` answers `{ "connections": [] }` and `/revenue` is all zeros — show the person "Connect Fanvue in smoooch" with a link to `https://smoooch.bio/app/revenue`. Connecting Fanvue itself is done by a person in smoooch; there is no endpoint for it. Poll every 15 minutes at most: that is how often smoooch itself asks Fanvue.

### `GET /connection`

```json
{
  "id": 12,
  "app": "Your app",
  "connectedAt": "2026-10-09T08:12:44.000Z",
  "connectedBy": { "email": "nova@example.com", "name": "Nova" },
  "workspace": { "id": 7, "name": "Nova Agency" },
  "plan": "pro",
  "limits": { "links": 400, "linksPerPage": 200, "seats": 5, "domains": 10, "statsDays": 730 },
  "ownPlan": "free",
  "grant": { "plan": "pro", "limits": { "links": 400 }, "until": null },
  "canGrant": true,
  "usage": { "links": 14, "seats": 1, "domains": 0 }
}
```

`plan` and `limits` are what the workspace has **now**. `ownPlan` is what it pays smoooch for itself. `grant` is what this connection gives, or `null`.

## The plan a connection gives

Your app decides what a connected workspace gets, and can change it at any time.

```bash
curl -X PUT https://smoooch.bio/api/v1/connection/grant \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{ "plan": "pro", "limits": { "links": 400 }, "until": null }'
```

| Field | | |
| --- | --- | --- |
| `plan` | required | A plan id: `free`, `starter`, `pro`, `plus` or `agency`. Its features and its limits apply. |
| `limits` | optional | Numbers that replace the plan's own: `links` (landing pages and direct links together, up to 100000), `linksPerPage` (buttons on one landing page, up to 1000), `seats` (team members, up to 500), `domains` (custom domains, up to 500), `statsDays` (how far back stats go, up to 3650). Leave one out to keep the plan's number. |
| `until` | optional | An ISO 8601 time after which the grant ends by itself, or `null` for no end. Useful as a safety net: set it a little past the person's billing period and renew it when they pay. |

The answer is the connection, as in `GET /connection`.

How it is applied:

- A grant **never lowers** anything. The workspace gets the higher of the two plans — its own and the granted one — and for each limit the larger number.
- Sending a new grant **replaces** the earlier one whole (it is not merged).
- `DELETE /connection/grant` takes the grant away and keeps the connection.
- A workspace that already pays smoooch for a plan keeps its subscription. If your grant is the same plan or higher, the subscription is kept at $0 for as long as the grant lasts; if it pays for a higher plan, it keeps paying for that. When the grant ends, the subscription is billed again as before, and its owners are emailed before the first charge. So a person who stops using your app stays on their plan without subscribing again.
- The grant ends when the connection ends, when `until` passes, or when the application is deleted on the owner site.
- When a grant ends and the workspace then holds more than its limits allow, nothing is deleted or taken offline: existing links keep working, and new ones cannot be made until there is room again.
- The person sees in smoooch that the plan comes with your app: under Plan & billing, and under Settings → Workspace → Connected apps.

What each plan includes by itself is on [smoooch.bio/pricing](https://smoooch.bio/pricing). Plans can change; send `limits` for any number your app has promised, so the person keeps it whatever the plan gives.

Typical use from your app:

```
person connects            → PUT /connection/grant  { plan and limits from your admin setting }
your plan changes          → PUT /connection/grant  { the new plan and limits }
their subscription ends    → DELETE /connection/grant        (keep the connection)
                             or POST /oauth/revoke           (end it altogether)
admin changes the setting  → PUT /connection/grant for every connection it applies to
```

## For an MCP server in your app

The tools map one to one onto the REST API; use the stored access token of the workspace the tool is called for, refreshing it first if it has less than a minute left.

| Tool | Call |
| --- | --- |
| List links | `GET /pages` and `GET /direct-links` (filter by `groupId` for one model) |
| Create a link | `POST /direct-links { destination, slug?, title?, groupId?, ageGate? }` → `201` with the link and its public `url` |
| Change where a link goes, rename it, switch it off | `PATCH /direct-links/:id { destination?, slug?, enabled? }` |
| Delete a link | `DELETE /direct-links/:id` |
| Is this name free? | `GET /names/:name` |
| How is a link doing? | `GET /direct-links/:id/stats?days=30`, `GET /pages/:id/stats?days=30` |
| Who is on the links right now? | `GET /live` |
| What did the links earn? Which source, country or device pays best? | `GET /revenue?days=30` (narrow with `directLinkId`, `pageId`, `creatorId`) |
| Groups | `GET/POST /groups`, `PATCH/DELETE /groups/:id` |
| Room left | `GET /connection` → `limits.links - usage.links` |

Errors are JSON `{ "error": "sentence a person can read", "field": "…", "code": "…" }`. Worth handling by name: `401` + `code: invalid_token` (refresh, then try once more), `402` + `code: plan_limit` (no room: raise the grant or tell the person), `409` (the address is taken), `429` (slow down; 600 calls a minute per address).

## Security, in one place

- The client secret and the refresh tokens live on your app's server only, encrypted at rest. Never in a browser, an app or a log.
- Always send and check `state`. Use PKCE.
- Redirect addresses are matched exactly. Add each environment's address (production, staging, localhost) to the application on the owner site.
- smoooch stores secrets, codes and tokens as SHA-256 only. A token that leaks can be ended from either side: `POST /oauth/revoke`, or Disconnect in smoooch.
- The links an application creates, changes or deletes, and every plan it sets, are written to the workspace's activity log, marked "through <app name>".
