Onboard & bill your users

If you are building a product on CloakAPI (like cloakup), you have two ways to turn your users into first-class CloakAPI accounts — each account gets its own wallet, its own metered relay, and is attributed to your app_id so your revenue is differentiable by source. This page covers onboarding and the two billing models.

Pre-launch — source until GA

The onboarding + consumer-billing endpoints described here exist in the gateway source and are covered by tests, but the platform is pre-launch. Treat the exact paths as stable-but-unreleased until the GA announcement. The attribution recorder that powers per-app_id analytics is off by default until CloakAPI enables it. Nothing here changes the blind-relay guarantee.

Your app_id

Every builder picks an opaque slug for each product they ship — lower-case [a-z0-9._-], ≤64 chars (e.g. acme-legal). It is the same app_id you send as the X-Cloak-App-Id relay header. It carries into both usage attribution and the accounts you provision, so CloakAPI can tell which of your products a user — and their spend — belongs to.

app_ids are not globally unique: two independent builders may pick the same slug for their own products; attribution always disambiguates by the (builder account, app_id) pair. A handful of names are reserved for CloakAPI’s own buckets (cloakapi, cloakapi-direct) and first-party products (cloakup) — you cannot claim those (see below).

Two ways to onboard an end-user

1. Public self-signup (your user signs themselves up)

Your user signs in from your page using the public /api/v1/consumer-auth/* surface (magic-link, password, or Google/Apple). Pass your app_id and the new account is tagged with it:

# Passwordless: your page requests a magic link, tagged to your app_id.
curl -X POST https://api.cloakapi.io/api/v1/consumer-auth/magic-link/request \
  -H 'Content-Type: application/json' \
  -d '{
        "email": "user@example.com",
        "app_id": "acme-legal",
        "return_to": "https://acme-legal.example/welcome",
        "app_name": "Acme Legal"
      }'

On the SDK this is the same account plumbing your dashboard signup uses — the user becomes a real CloakAPI user (account + organisation + wallet + trial credit on email verification).

The self-signup app_id is a self-asserted attribution hint (like a UTM tag). It is charset-validated and reserved buckets are dropped, but a public page cannot be cryptographically bound to you. For guaranteed, non-spoofable attribution and headless provisioning, use the builder endpoint below.

2. Builder-authenticated provisioning (you provision them)

Authenticate with your own cloak_ API key and provision (or link) an end-user account directly — no browser round-trip, ideal for bulk / server-side onboarding. The app_id is validated against your identity and claimed to your builder account, so attribution is binding:

curl -X POST https://api.cloakapi.io/api/v1/builder/users \
  -H 'Authorization: Bearer cloak_your_builder_key' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "lawyer@acme-legal.example", "app_id": "acme-legal", "name": "A. Lawyer" }'

{
  "user": {
    "account_id": 4821,
    "email": "lawyer@acme-legal.example",
    "email_verified": false,
    "organisation_id": "…",
    "app_id": "acme-legal"
  },
  "created": true
}

• Idempotent on email — a returning end-user is linked, never duplicated.
• The account is created unverified; the end-user gets the standard verification email, and their trial credit + relay key activate on verification (you cannot assert verification — that would be a trial-farming vector).
• Reserved / first-party slugs are refused (422 reserved_app_id): you cannot provision users under cloakup, cloakapi, or cloakapi-direct.
• List the accounts attributed to your app_id(s) — content-free (opaque handles only, no emails re-exposed):

curl https://api.cloakapi.io/api/v1/builder/users \
  -H 'Authorization: Bearer cloak_your_builder_key'
# → { "users": [ { "account_id": 4821, "app_id": "acme-legal",
#                  "email_verified": true, "created_at": "…" } ], "count": 1 }

This endpoint provisions accounts only — it is not an LLM call and charges nothing. Your users’ relay usage bills the standard markup to their own wallet (next section).

Two ways to bill

A. Your users pay their own metered wallet (markup)

Each provisioned end-user has their own CloakAPI wallet. Their relay calls are metered and CloakAPI’s standard markup is charged to their wallet — you simply onboard them. This is the simplest model and it keeps the no-free-relay invariant: every relayed call is billed markup through the metered gateway, no matter which of your users made it.

You can top-up an end-user’s wallet on their behalf, or let them top-up themselves — either way the money path stays in CloakAPI.

B. You bill a subscription on your own Stripe

Prefer a flat monthly plan? Bill your users on your own Stripe (your product, your prices, your margin) and let their usage draw CloakAPI’s markup from the wallet you fund. CloakAPI charges you (or the end-user wallet) the markup; how you package that to your customer is your business.

/consumer-billing is multi-app — keyed by app_id

The /api/v1/consumer-billing/* endpoints accept an optional app_id (default cloakup) validated against a server-side allowlist, and resolve the plan catalogue, Stripe prices, subscription records and revenue attribution per app. cloakup is the first app on the allowlist; an additional app bills here once its app_id is allowlisted and its plan catalogue + Stripe prices are provisioned server-side — until then its requests get a clean 503 billing_not_configured (never a mis-attributed cloakup charge). External builders can also keep using model A (metered wallets + markup) or run subscriptions on their own Stripe as in model B. Every subscription/charge is tagged with its app_id so revenue is differentiable by source.

Revenue differentiation by app_id

Because both usage (attribution facts) and billing records carry the app_id, CloakAPI can split revenue by product — cloakup vs cloakapi-direct vs each external builder — from one query. Provisioning through the builder endpoint makes that attribution binding; public self-signup makes it best-effort.

See also

• Attribution headers — the X-Cloak-App-Id / X-Cloak-End-User relay headers and the privacy line.
• Choose your integration — SDK, REST, MCP, proxy.
• Builder pricing — markup, the no-free-relay invariant.