Authentication
Every Platform API call is authenticated by a bearer key scoped to your platform account. Keys are stored as a hash, shown once, and rotated through support.
Every endpoint is authenticated by a bearer key sent on each request. Set a single Authorization header:
Authorization: Bearer sk_live_<token>The header must be exactly one Bearer <token> line. Tokens shorter than 16 characters are rejected before any lookup. The sk_live_ prefix is the issued convention — your key arrives in that form.
How keys are stored
A key is never persisted in plaintext. At issuance we compute a SHA-256 hash and keep that hash alongside an 8-character prefix for display. The plaintext is shown to you once, at issuance, and is never recoverable afterward. If you lose it, rotate.
Each key maps 1:1 to a single platform account. Every endpoint scopes all lookups to that account, so a request can only ever see and act on your tenants — you can never reach another partner's data, even by guessing an identifier.
Rotation
Rotation is admin-managed through support and is not host-callable. To rotate, request a new key and revoke the old one. Both keys can be active at the same time, so you can roll the new key out across a deploy window with no downtime before retiring the old one.
Errors
| Status | error | reason | When |
|---|---|---|---|
| 401 | unauthorized | missing_bearer | Header absent, not a single Bearer <token> line, or token shorter than 16 characters |
| 401 | unauthorized | invalid_key | Hash not found, or the key has been revoked |
| 401 | unauthorized | account_missing | Key is valid but the account row is gone |
| 401 | unauthorized | account_disabled | Account status = 'disabled' |
| 500 | internal_error | hash_failed / lookup_failed / account_lookup_failed | Server-side failure; safe to retry |
A draft account is not blocked here
Authentication succeeds for a key whose account is still draft — the
rejection happens at the endpoint, where platform-create and
platform-sso return 409 account_inactive. See
Onboarding for how an account moves from draft to
active.
The 500 reasons are server-side and transient. Retry with backoff — see Rate limits. For the full error model across every endpoint, see Error reference.
Introduction
The server-to-server integration surface for hosting companies reselling Swarmz — provision tenants, mint white-label dashboard sessions, meter usage, and run the full account lifecycle from your own billing system.
Data model
How platform accounts, tenants, and web-host users fit together — and which of them is the billing entity.