> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mlm-platform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a widget access token

> Creates a Widget Access Token (WAT) for embedding the referral widget.
The token is JWT-based and includes allowed origins for CORS validation.

**Security:**
- Tokens expire after 1 hour
- Origin must match configured allowed_widget_origins




## OpenAPI

````yaml api/openapi.yaml post /api/v1/widget/session
openapi: 3.1.0
info:
  title: MLM Platform API
  version: 1.0.0
  description: >
    The MLM Platform API enables tenant developers to integrate commission
    tracking,

    member management, and referral systems into their applications.


    ## Authentication

    All API requests require a tenant API key passed in the `x-tenant-api-key`
    header.


    ## Environments

    - **LIVE**: Production environment with real data

    - **SANDBOX**: Test environment for development and testing


    API keys are scoped to specific environments. Use sandbox keys for testing.


    The environment is derived from the API key used for the request.

    The platform returns the selected environment in the response header
    `X-Environment`.

    If you send an `X-Environment` request header, it is treated as
    optional/debug-only.
  contact:
    name: MLM Platform Support
    email: support@mlm-platform.example.com
  license:
    name: Proprietary
    url: https://mlm-platform.example.com/terms
servers:
  - url: https://app.mlm-platform.com
    description: Production API
  - url: http://localhost:3000
    description: Local Development
security:
  - TenantApiKey: []
tags:
  - name: Auth
    description: Token exchange, validation, refresh, and revocation for OIDC federation
  - name: Events
    description: Purchase and commission events
  - name: Users
    description: Member management
  - name: Leads
    description: Lead capture and tracking
  - name: Referrals
    description: Referral links and codes
  - name: Payout
    description: Payout methods metadata for dynamic payout setup forms
  - name: Payout Accounts
    description: Member payout accounts (create/list/update/delete)
  - name: KYC
    description: Member KYC start, status, and document submission
  - name: Admin KYC
    description: Admin KYC review queue, details, and actions
  - name: Widget
    description: Embeddable widget authentication
  - name: Webhooks
    description: Webhook receivers for third-party providers (Sumsub)
paths:
  /api/v1/widget/session:
    post:
      tags:
        - Widget
      summary: Create a widget access token
      description: |
        Creates a Widget Access Token (WAT) for embedding the referral widget.
        The token is JWT-based and includes allowed origins for CORS validation.

        **Security:**
        - Tokens expire after 1 hour
        - Origin must match configured allowed_widget_origins
      operationId: createWidgetSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWidgetSessionRequest'
            examples:
              basic:
                summary: Basic session
                value:
                  user_id: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Widget session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetSessionResponse'
          headers:
            X-Environment:
              $ref: '#/components/headers/X-Environment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Origin not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateWidgetSessionRequest:
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          format: uuid
          description: User ID for the widget session
    WidgetSessionResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT Widget Access Token
        expires_at:
          type: string
          format: date-time
        user_id:
          type: string
          format: uuid
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
        details:
          type: object
          additionalProperties: true
          description: Additional error details
  headers:
    X-Environment:
      description: >-
        Indicates the environment (LIVE or SANDBOX) the request was processed in
        (derived from API key)
      schema:
        type: string
        enum:
          - LIVE
          - SANDBOX
  responses:
    BadRequest:
      description: Bad Request - Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Invalid request body
            code: VALIDATION_ERROR
            details:
              field: email
              message: Invalid email format
    Unauthorized:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_api_key:
              summary: Missing API key
              value:
                error: Authentication required
                code: UNAUTHORIZED
            invalid_api_key:
              summary: Invalid API key
              value:
                error: Invalid API key
                code: INVALID_API_KEY
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: An unexpected error occurred
            code: INTERNAL_ERROR
  securitySchemes:
    TenantApiKey:
      type: apiKey
      in: header
      name: x-tenant-api-key
      description: >
        Tenant API key for authentication. Keys are scoped to specific
        environments

        (LIVE or SANDBOX). Obtain keys from the admin dashboard.

````