Skip to main content
Base URL: https://your-site.com/headless/v1

Authentication

There are two layers:
Required on every request (except browser-redirect routes):
The ?key=pk_live_... query parameter is accepted as an alternative.
Never put the Bearer token in localStorage or client state. The Next.js template uses a proxy route that keeps the token in an httpOnly cookie (see SDK and React).
OpenAPI states the required authentication for each endpoint: key only, key + Bearer (login required), key + optional Bearer, or none (browser redirects).

Response format

Error:
Always branch on error.code, never on message. Messages are translated and may change; codes are stable.
  • Pagination: ?page=2; the result is in meta.pagination.
  • Images are returned as absolute URLs.
  • Money values are numbers in the base currency; use the *Formatted fields for text converted to the visitor’s currency.

Account guards (403)

Logged-in accounts that have not completed a step receive these errors. Your frontend should catch them and send the player to the right screen: All error codes and their meaning appear in each endpoint’s x-error-codes in OpenAPI and in the MCP list_error_codes tool.

Language and currency

Translation files come from GET /i18n/{code}. The English text is the key; the SDK and template use it as t('English text').

Captcha (Cloudflare Turnstile)

The captcha field in GET /site/config contains enabled, provider, siteKey and whether each page needs it (pages: login, register, forgot_password, open_ticket, post_thread…). When the page needs it, send the Turnstile token from your form as captchaToken in the body. Failure returns CAPTCHA_FAILED. The <Turnstile page="login" onToken={...} /> component in the React package does this for you and renders nothing when no captcha is needed.

Module and feature checks

Before rendering a feature, check config.modules[slug].active. Endpoints of a disabled module return 404. In React use useModule('forum'), on the server isModuleActive(config, 'forum').

Redirect flows (handoff)

For actions where the browser must go to another site (payment page, Discord or an external provider) the API returns a one-time URL (handoff). In the SDK, leaderos.payments.start(intent) takes the browser there. The URL is valid for 60 seconds and can be used once. A payment request (PaymentIntent) returns one of these next values: After payment the player returns to the Payment success / error pages you defined in the panel. A CONTACT_REQUIRED error means a name/phone is required.

Rate limiting

The Headless API has no built-in rate limit (the main site has none either). On a live site, add rate-limit rules at a service such as Cloudflare for sensitive paths like /headless/v1/auth/*.

License and branding

  • The API validates your site’s license on the server (cached for 5 minutes).
  • If config.branding.canRemove is false, the “Powered by LeaderOS” link must be visible in your frontend.