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:
- 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.
- A person clicks "Connect smoooch" in the application. They land on smoooch, choose one workspace and press Connect.
- The application's server swaps the code it gets back for an access token and a refresh token.
- 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:
- 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://localhostis 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,prooragency) and, if wanted, limits (see 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
stateis 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. OnlyS256.- 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)
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" }
}
- 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
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": "…" }.
| 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 — 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
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. ReadinggroupIdback 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:
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 | ||
|---|---|---|
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/granttakes 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
untilpasses, 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. 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>".
API keys for your own scripts are made in the app, under API.