Developers · Connect API

Connect: developer docs

Link your app to a creator's show-me-love page, then read their support link and totals with their permission. Plain HTTP, no SDK.

Overview

Connect lets your app link one of its users to their show-me-love page. After the user presses Allow, your server can look up their support link (and, if they choose, their totals) with a few plain HTTP calls. There is no SDK to install: everything below uses fetch.

The flow: your server asks for a session, the user approves on show-me-love, we send them back to your callback with a short-lived code, and your server swaps that code for a connection. Each of your users is identified by a user_ref, an id you pick from your own system (1 to 128 characters).

Quickstart

1. In Developers, create a Sandbox app and register your callback link, for example http://localhost:3001/api/sml/callback.
2. Create an API key. It is shown once, so copy it straight into your server env.
3. Set the environment on your server:

   SML_ORIGIN=https://your-show-me-love-host
   SML_CLIENT_ID=sml_app_xxxxxxxxxxxxxxxx
   SML_API_KEY=sml_test_xxxxxxxx   # server only, never in the browser
   APP_ORIGIN=http://localhost:3001
   SML_REDIRECT_URI=http://localhost:3001/api/sml/callback

4. Add a small helper and a connect route. Both run on your server.

   // lib/sml.ts (server only)
   export async function sml(path: string, init: { method?: string; body?: unknown } = {}) {
     const res = await fetch(process.env.SML_ORIGIN + "/api/connect" + path, {
       method: init.method ?? "GET",
       headers: {
         Authorization: "Bearer " + process.env.SML_API_KEY,
         "X-Client-Id": process.env.SML_CLIENT_ID!,
         ...(init.body ? { "Content-Type": "application/json" } : {}),
       },
       body: init.body ? JSON.stringify(init.body) : undefined,
       cache: "no-store",
     });
     return { status: res.status, data: await res.json().catch(() => ({})) };
   }

   // app/api/sml/connect/route.ts
   import { cookies } from "next/headers";
   import { sml } from "@/lib/sml";
   
   export async function POST() {
     const userRef = await myOwnSessionUserId(); // from YOUR session, never from the request
     const state = crypto.randomUUID();
     (await cookies()).set("sml_state", state, { httpOnly: true, sameSite: "lax", maxAge: 600, path: "/" });
     const { status, data } = await sml("/sessions", {
       method: "POST",
       body: { user_ref: userRef, redirect_uri: process.env.SML_REDIRECT_URI, state },
     });
     if (status !== 200) return Response.json(data, { status: 502 });
     return Response.json({ url: data.authorize_url }); // the browser goes there
   }

5. Add the callback, then show the support link:

   // app/api/sml/callback/route.ts
   import { cookies } from "next/headers";
   import { sml } from "@/lib/sml";
   
   export async function GET(req: Request) {
     const q = new URL(req.url).searchParams;
     const jar = await cookies();
     const saved = jar.get("sml_state")?.value;
     jar.delete("sml_state"); // single use, whatever happens next
     const home = (qs = "") => Response.redirect(process.env.APP_ORIGIN + "/" + qs);
     if (!saved || q.get("state") !== saved) return home("?error=Bad+state");
     if (q.get("error") === "access_denied") return home("?denied=1");
     const { status, data } = await sml("/token", { method: "POST", body: { code: q.get("code") } }); // 200 { connected: true }
     return status === 200 ? home() : home("?error=" + encodeURIComponent(data.error ?? "Could not connect"));
   }

   // Anywhere on the server
   const { status, data } = await sml("/connection?user_ref=" + encodeURIComponent(userRef));
   if (status === 200) {
     // data.support_url, data.display_name, data.username, data.earnings_shared
   } else if (status === 404) {
     // not connected: show the Connect button
   }

A complete working app lives in examples/connect-starter in the repository.

HTTP API

Base URL: your show-me-love origin. Every call needs Authorization: Bearer <key> and X-Client-Id: <client id>. POST bodies must be JSON with Content-Type: application/json. Failures return { "error": "…" } with the status shown below. Each app can make 120 calls a minute.

curl -X POST "$SML_ORIGIN/api/connect/sessions" \
  -H "Authorization: Bearer $SML_API_KEY" -H "X-Client-Id: $SML_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d "{\"user_ref\":\"u_123\",\"redirect_uri\":\"$SML_REDIRECT_URI\"}"

{ "user_ref": "u_123", "redirect_uri": "https://app.example.com/api/sml/callback", "state": "random-string" }

200 { "authorize_url": "https://…/connect/authorize?req=…" }  (valid for 10 minutes)

{ "code": "…" }

200 { "connected": true }

200 { "username": "ada", "display_name": "Ada", "support_url": "https://…/@ada", "earnings_shared": false }

200 { "total_received": "12.50", "currency": "USDT", "treats": 5 }  (sandbox apps always get these sample numbers)

{ "user_ref": "u_123" }

200 { "ok": true }

The callback: on Allow, the user returns to your redirect link with ?code=…&state=…. On Deny they return with ?error=access_denied&state=…. If you sent no state, none comes back.

Security checklist

• Keys stay on your server. Never put SML_API_KEY in browser code, a mobile app, or a public repo. If one leaks, revoke it in Developers and make a new one.
• Take user_ref from your own session. Never read it from a form field, query string or request body the browser controls, or anyone could link themselves to someone else's account.
• Use a random state: set it in an httpOnly cookie when you start, and compare it on the callback before exchanging the code.
• Register exact redirect links. Matching is character for character: no wildcards, no trailing-slash tolerance. Use https (http only for localhost). No # fragments.
• Test the unhappy paths: press Deny and make sure your app copes with access_denied; revoke the app from the Share page and make sure /connection then returns 404 and your UI says not connected.
• Use the sandbox first. Sandbox keys (sml_test_…) only work with sandbox apps, and sandbox earnings are sample numbers.

Going live

1. Create a separate Live app in Developers, with your production redirect links (https only).
2. Create a live key (sml_live_…) and put it, with the live client id, in your production env. Keep the sandbox values for development.
3. Update SML_ORIGIN, APP_ORIGIN and SML_REDIRECT_URI to the production addresses.
4. Run the full flow once with a real creator account: Connect, Allow, support link shows, revoke, not connected.
5. Live /earnings returns the creator's real totals, so only ask for it if you need it.