> ## Documentation Index
> Fetch the complete documentation index at: https://developer.leaderos.net/llms.txt
> Use this file to discover all available pages before exploring further.

# API Basics

> Authentication, response format, error codes, localization, currency, captcha and the payment flow.

Base URL: `https://your-site.com/headless/v1`

## Authentication

There are two layers:

> [tab] Public key
>
> Required on every request (except browser-redirect routes):
>
> ```http theme={null}
> X-LeaderOS-Key: pk_live_XXXXXXXX
> ```
>
> The `?key=pk_live_...` query parameter is accepted as an alternative.

> [tab] Bearer token
>
> The player's token for endpoints that need a login:
>
> ```http theme={null}
> Authorization: Bearer <token>
> ```
>
> The token comes from the `POST /auth/login` or `POST /auth/register` response and is revoked with `POST /auth/logout`.

> [!WARNING]
>
> **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](https://developer.leaderos.net/headless/en/sdk-and-react.md)).

OpenAPI states the required authentication for each endpoint: key only, key + Bearer (login required), key + optional Bearer, or none (browser redirects).

## Response format

```json theme={null}
{
  "success": true,
  "data": { },
  "message": "Translated message (if any)",
  "meta": {
    "pagination": { "page": 1, "perPage": 10, "total": 42, "lastPage": 5 },
    "seo": { "page": "blog", "title": "…", "description": "…", "image": "…" }
  }
}
```

Error:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "fields": { "email": { "required": "E-mail is required" } }
  }
}
```

**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:

| Code | Meaning | What the frontend does |
| - | - | - |
| `EMAIL_REQUIRED` | Account has no e-mail | Ask for it → `POST /auth/email` |
| `TFA_REQUIRED` | 2FA not verified | Ask for the code → `POST /tfa/verify` |
| `EMAIL_NOT_VERIFIED` | E-mail not verified | Show the verification screen |
| `UNAUTHENTICATED` (401) | Token required | Redirect to login |
| `INVALID_TOKEN` (401) | Token expired / logged out | Drop the token, show login |
| `ACCOUNT_BANNED` | Account is banned | Show an info screen |
| `MAINTENANCE` (503) | Maintenance mode | Show the maintenance 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

| Header | Effect |
| - | - |
| `X-Locale: en` | Language of messages and content. Alternatives: `?lang=en`, `Accept-Language` |
| `X-Currency: USD` | Currency used to display prices |

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:

| `next` | What to do |
| - | - |
| `redirect` | Send the browser with `api.payments.start(intent)` |
| `manual` | Show the `/payment/pay/manual/{orderId}` page |
| `success` | Paid with credits, go to the success page |
| `external` | Open `paymentUrl` and show the `notice` text |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.