Single sign-on

Mint a short-lived redirect that lands a web-host user in their dashboard, already logged in. Send their browser to it — mint a fresh token on every click.

POSThttps://api.swarmz.net/functions/v1/platform-sso

Mints a short-lived redirect that lands a WHU in their dashboard, logged in. Take the returned URL and send the customer's browser there with a 302. The token is embedded in the URL and is consumed on landing.

Address the tenant by tenant_id or external_ref — supply exactly one.

Parameters

Prop

Type

Request

curl -X POST https://api.swarmz.net/functions/v1/platform-sso \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "whmcs:1234",
    "ttl_seconds": 1800
  }'

const res = await fetch('https://api.swarmz.net/functions/v1/platform-sso', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_ref: 'whmcs:1234',
    ttl_seconds: 1800,
  }),
});

const { redirectTo } = await res.json();
// Send the customer's browser to redirectTo with a 302.

import requests

res = requests.post(
    "https://api.swarmz.net/functions/v1/platform-sso",
    headers={"Authorization": "Bearer sk_live_..."},
    json={"external_ref": "whmcs:1234", "ttl_seconds": 1800},
)
redirect_to = res.json()["redirectTo"]
# Send the customer's browser to redirect_to with a 302.

Response

{
  "success": true,
  "redirectTo": "https://acme.swarmz.net/sso?token=<jwt>&workspace=<uuid>"
}

The envelope is success / redirectTo

Unlike the other endpoints, SSO returns success and redirectTo rather than ok. Read redirectTo and issue the 302.

Errors

Status	`error`	`reason`	When
400	`missing_fields`	`tenant_id or external_ref required`	Neither identifier supplied
401	`unauthorized`	—	See Authentication
404	`tenant_not_found`	—	No tenant matched the identifier under your account
404	`account_not_found`	—	Defensive — your account row was not found
405	`method_not_allowed`	—	Anything other than `POST`
409	`suspended`	—	The tenant is suspended
409	`account_inactive`	—	Your platform account is not `active` (e.g. `draft`)
410	`terminated`	—	The tenant has been terminated
429	`rate_limited`	`per_key` / `per_ip`	Rate limit hit — see Rate limits
500	`internal_error`	—	Server-side failure; safe to retry

Idempotency

SSO has no idempotency key. Each call mints a fresh token. See Idempotency.

Notes

Mint per click — never cache a token

There is no server-side token store and no revoke list. To force a WHU out, suspend the tenant — the next SSO call then returns 409 suspended. Do not cache and re-issue tokens; mint a fresh one on each click. ttl_seconds is capped at 3600, so for a longer session re-call on the next click rather than requesting a longer token.

SSO is the hot path and has a much higher budget than the other endpoints: 600 requests/min per key and 1200/min per IP. See Rate limits.