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

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

ValueLooks likeGoes into your app as
Client IDsbc_…SMOOOCH_CLIENT_ID
Client secretsbs_…SMOOOCH_CLIENT_SECRET
smoooch addresshttps://smoooch.bioSMOOOCH_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:

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

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)

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.

{
  "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" }
}

4. A new access token

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:

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": "…" }.

StatuserrorMeaning
401invalid_clientUnknown client ID or wrong secret
400invalid_grantCode wrong, used, older than five minutes, or for another redirect address; PKCE verifier wrong; refresh token wrong or connection ended
400unsupported_grant_typegrant_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 — 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:

WhatEndpoints
The workspace, its plan, limits and how much is usedGET /workspace
Landing pages: list, one page with its buttons and socials, statsGET /pages, GET /pages/:id, GET /pages/:id/stats, GET /items/:id/stats
Direct links: list, read, create, change, delete, statsGET/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, deleteGET/POST /groups, PATCH/DELETE /groups/:id
Which group a link is ingroupId on a direct link (POST/PATCH); PATCH /pages/:id with { "groupId": 3 } or null
All stats of the workspace, and live numbersGET /stats, GET /live
The connection itself, and the plan it givesGET /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

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:

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:

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

{
  "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.

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
planrequiredA plan id: free, starter, pro, plus or agency. Its features and its limits apply.
limitsoptionalNumbers 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.
untiloptionalAn 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:

What each plan includes by itself is on 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.

ToolCall
List linksGET /pages and GET /direct-links (filter by groupId for one model)
Create a linkPOST /direct-links { destination, slug?, title?, groupId?, ageGate? } → 201 with the link and its public url
Change where a link goes, rename it, switch it offPATCH /direct-links/:id { destination?, slug?, enabled? }
Delete a linkDELETE /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)
GroupsGET/POST /groups, PATCH/DELETE /groups/:id
Room leftGET /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

API keys for your own scripts are made in the app, under API.