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

# Derive Scoped Token

> Creates a new scoped API token for the authenticated partner. Requires Privy authentication (Bearer token). The token secret is returned once at creation — store it securely. Requested scopes must be a subset of the partner's allowed scopes.

<Info>
  Requires **Privy authentication**. Pass the `token` field from the Privy authenticate response (the identity token) in the `identity` header as `Bearer <token>`. Do **not** use `privy_access_token`. HMAC and API key auth are not accepted for this endpoint.
</Info>

<Warning>
  The `secret` field is returned **once** at creation time. Store it securely — it cannot be retrieved again.
</Warning>

### Scopes

| Scope               | Description                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `trading`           | Place and cancel orders. Default scope. Required for `delegated_signing`.                  |
| `account_creation`  | Create sub-account profiles under your partner account.                                    |
| `delegated_signing` | Server signs orders on behalf of sub-accounts via Privy server wallet. Requires `trading`. |

If `scopes` is omitted from the request body, the token is created with `["trading"]` only.

Requested scopes must be a subset of your partner's `allowedScopes` (see [Get Partner Capabilities](/api-reference/api-tokens/get-capabilities)).

### Using the token

After deriving a token, authenticate subsequent requests using HMAC signing with the returned `apiKey` (token ID) and `secret`. See [HMAC Request Signing](/developers/authentication#hmac-request-signing) for the signing protocol.


## OpenAPI

````yaml POST /auth/api-tokens/derive
openapi: 3.0.0
info:
  title: Limitless Exchange API
  description: >-
    Production-ready REST API for prediction market trading, portfolio
    management, and market data on Limitless Exchange (Base L2).
  version: '1.0'
  contact:
    name: API Support
    url: https://limitless.exchange
    email: help@limitless.network
servers:
  - url: https://api.limitless.exchange
    description: Production API
security: []
tags:
  - name: Authentication
    description: User authentication and session management
  - name: Markets
    description: Browse, search, and analyze prediction markets
  - name: Market Navigation
    description: Navigation tree, market pages, and property filters
  - name: Trading
    description: Create, manage, and cancel orders
  - name: Portfolio
    description: Position tracking, trade history, and performance
  - name: API Tokens
    description: Scoped API token management for partner integrations
  - name: Partner Accounts
    description: Sub-account creation and allowance recovery for partner integrations
  - name: System
    description: Public API state and availability information
paths:
  /auth/api-tokens/derive:
    post:
      tags:
        - API Tokens
      summary: Derive scoped API token
      description: >-
        Creates a new scoped API token for the authenticated partner. Requires
        Privy authentication (Bearer token). The token secret is returned once
        at creation — store it securely. Requested scopes must be a subset of
        the partner's allowed scopes.
      operationId: ApiTokenController_deriveToken
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeriveApiTokenRequest'
      responses:
        '201':
          description: Token created successfully. The secret is only returned once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeriveApiTokenResponse'
        '400':
          description: Invalid scopes or profile not found
        '401':
          description: Requires Privy authentication
        '403':
          description: >-
            Token management not enabled or requested scopes not allowed for
            this partner
      security:
        - HmacAuth: []
components:
  schemas:
    DeriveApiTokenRequest:
      type: object
      properties:
        label:
          type: string
          maxLength: 128
          description: Human-readable label for the token
          example: production-trading-bot
        scopes:
          type: array
          items:
            type: string
            enum:
              - trading
              - account_creation
              - delegated_signing
          description: >-
            Scopes to grant. Defaults to ["trading"] if omitted. Must be a
            subset of the partner's allowed scopes. `delegated_signing` requires
            `trading`.
          example:
            - trading
            - account_creation
    DeriveApiTokenResponse:
      type: object
      properties:
        apiKey:
          type: string
          description: >-
            The token ID, used as the `lmts-api-key` header value for HMAC
            requests
          example: dGVzdC10b2tlbi0x
        secret:
          type: string
          description: >-
            Base64-encoded secret for HMAC signing. Returned once — store
            securely.
          example: c2VjcmV0LWtleS1leGFtcGxlLWJhc2U2NC1lbmNvZGVk
        tokenId:
          type: string
          description: Same as apiKey. The unique token identifier.
          example: dGVzdC10b2tlbi0x
        createdAt:
          type: string
          format: date-time
          description: Token creation timestamp
        scopes:
          type: array
          items:
            type: string
          description: Granted scopes
          example:
            - trading
            - account_creation
        profile:
          type: object
          properties:
            id:
              type: integer
              description: Partner profile ID
              example: 42
            account:
              type: string
              description: Partner wallet address
              example: '0x27b4afBD88fE7c88c6897BB0b4ADE338D0401E37'
      required:
        - apiKey
        - secret
        - tokenId
        - createdAt
        - scopes
        - profile
  securitySchemes:
    HmacAuth:
      type: apiKey
      in: header
      name: lmts-api-key
      description: >-
        Scoped API token with HMAC-SHA256 signing. Requires three headers:
        lmts-api-key (token ID), lmts-timestamp (ISO-8601), lmts-signature
        (Base64-encoded HMAC). See Authentication docs for details.

````