> ## 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.

# Link a provider account



## OpenAPI

````yaml /headless/openapi.json post /account-linking/{provider}/link
openapi: 3.1.0
info:
  title: LeaderOS Headless API
  version: 1.0.0
  description: >-
    JSON API to build your own LeaderOS frontend (React, Next.js, Vue...).


    ## Authentication

    - **Public key** — every request sends `X-LeaderOS-Key: pk_live_...`
    (Dashboard → Settings → Headless). It is public: browser requests must come
    from an *allowed origin*; requests without an `Origin` header (SSR, server
    actions) are accepted.

    - **User token** — `POST /auth/login` returns a `token`. Send it as
    `Authorization: Bearer <token>`.


    ## Locale & currency

    `X-Locale: tr` and `X-Currency: EUR` (or `?lang=` / `?currency=`). Messages
    in responses are translated.


    ## Errors

    Every error is `{ success: false, error: { code, message, fields? } }`.
    Switch on `error.code`, never on the message. Account guards:
    `EMAIL_REQUIRED`, `TFA_REQUIRED`, `EMAIL_NOT_VERIFIED` (403) tell the
    frontend which screen to show.


    ## Captcha

    If `GET /site/config` → `captcha.pages.<page>` is true, render a Cloudflare
    Turnstile widget with `captcha.siteKey` and send its token as
    `captchaToken`.


    ## Branding

    If `config.branding.canRemove` is false you must display “Powered by
    LeaderOS” linking to `config.branding.url`.
  x-logo:
    url: https://www.leaderos.net/favicon.ico
servers:
  - url: '{siteUrl}/headless/v1'
    description: Your LeaderOS site
    variables:
      siteUrl:
        default: https://your-site.com
        description: Your LeaderOS website URL (no trailing slash)
security:
  - publicKey: []
tags:
  - name: Site
    description: Site configuration, layout data, translations.
  - name: Auth
    description: Login, registration, password reset, session.
  - name: Account
    description: >-
      The logged-in player's profile, history and settings. Every endpoint needs
      the user token.
  - name: Applications
    description: 'Staff application forms. Module: `application`.'
    x-module: application
  - name: Bazaar
    description: 'Player marketplace for in-game items. Module: `bazaar`.'
    x-module: bazaar
  - name: Blog
    description: 'Posts, categories, tags, comments. Module: `blog`.'
    x-module: blog
  - name: Changelog
    description: 'Release notes. Module: `changelog`.'
    x-module: changelog
  - name: Chest
    description: 'Purchased products waiting for delivery. Module: `chest`.'
    x-module: chest
  - name: Credits
    description: >-
      Credit balance top-ups and transfers. Module: `credit`. Main switched
      between two modes by redirecting: when
      `config.modules.credit.settings.creditPackageStatus` is 1 use packages,
      otherwise charge (the other mode answers `409`). Buying returns a
      PaymentIntent (see Payments).
    x-module: credit
  - name: Downloads
    description: 'Downloadable files. Module: `download`.'
    x-module: download
  - name: Email verification
    description: >-
      Verify the account e-mail. Module: `email_verification`. While unverified,
      other endpoints answer `403 EMAIL_NOT_VERIFIED`. The e-mail link opens
      your frontend route `verifyEmail` (default `/verify-email/{token}`), which
      calls `POST /email-verification/verify/{token}` with the user's token.
    x-module: email_verification
  - name: Forms
    description: 'Custom forms. Module: `form`.'
    x-module: form
  - name: Fortune Wheel
    description: >-
      Spin for prizes. Module: `lottery`. Free wheels can be spun again after
      their `duration` (hours).
    x-module: lottery
  - name: Forum
    description: >-
      Forum. Module: `forum`. Visibility and rights are per category and role
      (`VIEW_FORUM`, `CREATE_TOPICS`, `CREATE_REPLIES`, `MODERATE_FORUM`);
      anything the user may not see is a 404. Message bodies are markdown: send
      raw markdown, receive rendered HTML (raw markdown only from the `edit`
      endpoints).
    x-module: forum
  - name: Games
    description: 'Game pages. Module: `games`.'
    x-module: games
  - name: Gaming Night
    description: >-
      Weekly timed discounts paid with credits. Module: `gaming_night`. Outside
      the event window `GET /gaming-night` returns a countdown and the product
      endpoints answer 404.
    x-module: gaming_night
  - name: Gift codes
    description: 'Redeem codes for a product or credits. Module: `gift`.'
    x-module: gift
  - name: Help
    description: 'Help center. Module: `help`.'
    x-module: help
  - name: Leaderboards
    description: >-
      Server leaderboards read from a MySQL table. Module: `leaderboards`.
      Connection credentials are never exposed.
    x-module: leaderboards
  - name: Linked accounts
    description: >-
      Discord and third-party account linking / login. These flows leave your
      site: each `POST` returns a one-time `url` for `window.location`. The
      provider returns to the API, which redirects the browser to your frontend:
      `accountLinked?status=&provider=&message=` after linking,
      `loginCallback?exchange=` (or `error=`) after a login. See Dashboard →
      Headless → Frontend routes.
    x-module: account_linking
  - name: Members
    description: >-
      Public member profiles. Module: `player`. Only public data is returned (no
      e-mail, credits or IPs).
    x-module: player
  - name: Server
    description: Play, staff and vote pages.
  - name: Pages
    description: 'Custom pages (rules, terms, privacy...). Module: `page`.'
    x-module: page
  - name: Payments
    description: >-
      Payments run in the browser: the purchase endpoints create the order and
      return a **PaymentIntent**. For `next: redirect` navigate to `paymentUrl`
      (one-time handoff URL, no headers needed); the API starts the gateway
      (redirect or auto-submitted form). The gateway notifies
      `/payments/callback/{provider}` and sends the browser to
      `/payments/return/{status}`, which redirects to the frontend routes
      `paymentSuccess` / `paymentError` (Dashboard → Settings → Headless;
      defaults `/payment/success?order={orderId}`,
      `/payment/error?order={orderId}&error={code}`). Gateways that need the
      buyer's name/phone answer `CONTACT_REQUIRED` → `PATCH /account/contact`,
      then retry. Gateways whose notification URL is fixed in the provider panel
      can keep main's `/callback/{provider}`; both complete the same order.
    x-module: store
  - name: Punishments
    description: >-
      Ban/mute/kick/warning lists read from the LiteBans or PunishmentHistory
      plugin database. Module: `punishments`.
    x-module: punishments
  - name: Store
    description: >-
      Store catalog, cart and orders. Module: `store` (not with the Tebex
      store). **Amounts:** plain numbers are in the store's base currency (what
      a payment charges); `*Formatted` strings are converted to the selected
      currency (`X-Currency`) and use the credit text when the store is
      credit-only. If `config.modules.store.settings.redirect` is set, every
      store endpoint answers `409 STORE_REDIRECT` with `url` (the store lives
      elsewhere).
    x-module: store
  - name: Suggestions
    description: >-
      Player suggestions with votes and replies. Module: `suggestions`. Bodies
      are markdown (send raw, receive HTML; raw only from `edit` endpoints).
    x-module: suggestions
  - name: Support
    description: >-
      Support tickets of the logged-in user. Module: `support`. Player messages
      are markdown (send raw, receive HTML); staff/AI messages are HTML.
    x-module: support
  - name: Two-factor auth
    description: >-
      TOTP two-factor authentication. Module: `tfa`. After login with
      `tfaRequired: true`, every other endpoint answers `403 TFA_REQUIRED` until
      `POST /tfa/verify` succeeds.
    x-module: tfa
paths:
  /account-linking/{provider}/link:
    post:
      tags:
        - Linked accounts
      summary: Link a provider account
      operationId: startAccountLink
      parameters:
        - name: provider
          in: path
          required: true
          description: Provider slug
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                      url:
                        type: string
                        format: uri
                        description: >-
                          Navigate the browser here (window.location). Valid for
                          60 seconds, single use.
                      expiresAt:
                        type: string
                        format: date-time
                    required:
                      - token
                      - url
                      - expiresAt
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
      security:
        - publicKey: []
          bearerAuth: []
components:
  responses:
    Unauthenticated:
      description: Missing/invalid API key or user token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: UNAUTHENTICATED
              message: ...
    Forbidden:
      description: >-
        Forbidden, origin not allowed or account guard (EMAIL_REQUIRED,
        TFA_REQUIRED, EMAIL_NOT_VERIFIED)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: FORBIDDEN
              message: ...
    NotFound:
      description: Not found or module disabled
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: NOT_FOUND
              message: ...
    Conflict:
      description: Conflict (already exists / already logged in)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: CONFLICT
              message: ...
  schemas:
    Error:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable error code (see ERROR_CODES.md).
            message:
              type: string
              description: Translated, human readable.
            fields:
              type: object
              additionalProperties:
                type: object
                additionalProperties:
                  type: string
              description: 'Validation errors per field: { field: { rule: message } }'
          additionalProperties: true
          x-optional:
            - fields
  securitySchemes:
    publicKey:
      type: apiKey
      in: header
      name: X-LeaderOS-Key
      description: Public key from Dashboard → Settings → Headless (pk_live_...).
    bearerAuth:
      type: http
      scheme: bearer
      description: User token from POST /auth/login or /auth/register.

````

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