Skip to main content
All Headless settings live in the admin panel under Settings → Headless API (/dashboard). You need the MANAGE_SETTINGS permission. The API Documentation button at the top opens the interactive docs (/headless/docs) in a new tab.
The Headless API is not a module; it is a built-in feature of the site. Settings are stored in the Settings table and every change is written to the admin log.

Headless API Status

The master switch. While it is off, every /headless/v1/* request returns 404 HEADLESS_DISABLED. The toggle is saved the moment you flip it; you do not need to press Save.
Make sure the API is on before you publish your theme. For maintenance, use LeaderOS’s maintenance mode instead of turning the API off: during maintenance staff can keep using the API while everyone else gets 503 MAINTENANCE.

Public Key

The key sent in the X-LeaderOS-Key header of every API request (pk_live_ + 32 hex characters).
  • It is public by design: it may appear in browser code. There is no secret key. Security comes from allowed origins and per-player Bearer tokens.
  • Copy: copies the key to the clipboard.
  • Generate New Key: creates a new key. You are asked to confirm because every frontend using the old key stops working until you update it (INVALID_API_KEY). Use it if the key leaks or a team member leaves.
  • API URL: https://your-site.com/headless/v1. In the SDK you pass the site root (https://your-site.com) as baseUrl.

Allowed Origins (CORS)

The list of websites that may call the API directly from a browser. Write one origin per line (scheme + host + optional port, no path):
  • *. works as a subdomain wildcard.
  • Your site’s own address and the Frontend URL below are always allowed.
  • Requests without an Origin header (server-side, curl, mobile apps) are always accepted, because the origin check only targets browsers.
  • An invalid format (for example a trailing path or a missing scheme) is rejected when you save.

Allow all origins (development only)

Turns the origin check off completely. Handy for local development, but it must be off on a live site; otherwise any website could call the API from a browser with your key.

Frontend URL & Pages

The API sends players to your frontend from e-mails and from external providers (payments, login). Define your frontend address and page paths here.

Frontend URL

The root of your frontend, for example https://shop.example.com. If empty, your LeaderOS site address is used. No trailing / (it is stripped when saving).

Page paths

Each row is a path template and must start with /. Leave it empty to use the default (shown as the placeholder). Placeholders such as {token} are filled in automatically; only the placeholders listed under each field are allowed.
Create these pages in your theme, or change the paths to match your own pages. Otherwise the password-reset e-mail or the payment return will land on a 404. The template from create-leaderos-theme already has all of them.

Sessions

Session lifetime (minutes): how long a session without “remember me” survives inactivity. Default 1440 (1 day), allowed range 5 – 525600. The lifetime is extended on every request. Sessions started with “remember me” last 1 year. When the password or e-mail changes, all sessions are closed like on the main site and the player who made the change receives a new token (the SDK stores it automatically).

Endpoint Groups

You can switch off feature groups your frontend does not need. A disabled group returns 404. Only the site group cannot be disabled. Groups of disabled modules are unavailable anyway.
Apply least privilege: switching off groups you do not use shrinks the attack surface. If you only build a store, for example, you can turn off forum, support and suggestions.

Developer Resources

The section at the bottom of the page links to the interactive docs, openapi.json, llms.txt and llms-full.txt. See Developer resources.

Saving

The status toggle and public-key actions apply immediately. All other settings (origins, Frontend URL, page paths, session lifetime, groups) are saved with the Save Changes button at the bottom of the page.