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

# Create an embed token

> Mint a short-lived, partner-scoped token for the embedded referral dashboard. Safe to send to the browser. With partner (email and program_id), the partner is created when the program has none with that email, so one call covers a user's first visit.


## OpenAPI

````yaml /api-reference/openapi.json post /v2/embed-tokens
openapi: 3.1.0
info:
  title: Tolt Public API
  version: 2.0.0
servers:
  - url: https://platform.tolt.dev
    description: Development
security:
  - bearerAuth: []
paths:
  /v2/embed-tokens:
    post:
      tags:
        - Embed
      summary: Create an embed token
      description: >-
        Mint a short-lived, partner-scoped token for the embedded referral
        dashboard. Safe to send to the browser. With partner (email and
        program_id), the partner is created when the program has none with that
        email, so one call covers a user's first visit.
      operationId: createEmbedToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                partner_id:
                  type: string
                  minLength: 1
                  description: >-
                    Id of an existing partner (part_...). Send this or partner,
                    not both.
                partner:
                  type: object
                  properties:
                    email:
                      type: string
                      format: email
                      description: Email of the partner, matched without regard to case.
                    program_id:
                      type: string
                      minLength: 1
                      description: Program the partner belongs to (prg_...).
                    first_name:
                      type: string
                      minLength: 1
                      maxLength: 150
                      description: First name, used only when the partner is created.
                      example: Sam
                    last_name:
                      type: string
                      minLength: 1
                      maxLength: 150
                      description: Last name, used only when the partner is created.
                      example: Rivera
                    group_id:
                      type: string
                      minLength: 1
                      description: >-
                        Group for a newly created partner. Defaults to the
                        program's default group.
                  required:
                    - email
                    - program_id
                  description: >-
                    Find the partner by email within the program, or create them
                    (active, with a referral link) when the program has no
                    partner with that email. Send this or partner_id, not both.
              description: >-
                Send exactly one of partner_id or partner. Sending both or
                neither returns 400.
      responses:
        '200':
          description: The embed token
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Request successful
                  data:
                    $ref: '#/components/schemas/EmbedToken'
                required:
                  - success
                  - message
                  - data
              example:
                success: true
                message: Embed token created
                data:
                  token: example-embed-token
                  expires_at: '2026-10-01T12:00:00Z'
                  partner_id: part_8fKq2LmZx7RtYw3nVbHc5dPj
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: 'request: Invalid input: expected object, received null'
                code: validation_error
                doc_url: https://docs.tolt.com/errors#validation_error
                errors:
                  - field: request
                    message: 'Invalid input: expected object, received null'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: Unauthorized
                code: unauthorized
                doc_url: https://docs.tolt.com/errors#unauthorized
        '404':
          description: >-
            No such partner, the partner is invited, suspended or rejected, or
            the program isn't active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                message: >-
                  No such partner, the partner is invited, suspended or
                  rejected, or the program isn't active
                code: not_found
                doc_url: https://docs.tolt.com/errors#not_found
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    EmbedToken:
      type: object
      properties:
        token:
          type: string
          example: example-embed-token
        expires_at:
          type: string
          format: date-time
          example: '2026-10-01T12:00:00Z'
        partner_id:
          type: string
          example: part_8fKq2LmZx7RtYw3nVbHc5dPj
          description: The partner the token is for, including one this call just created.
      required:
        - token
        - expires_at
        - partner_id
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Human-readable explanation. May change; branch on code instead.
        code:
          type: string
          enum:
            - bad_request
            - validation_error
            - invalid_reference
            - invalid_cursor
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - already_exists
            - commission_paid
            - commission_frozen
            - transaction_refunded
            - commission_exists
            - rate_limited
            - payload_too_large
            - internal_error
          description: Stable machine-readable error code.
          example: not_found
        doc_url:
          type: string
          example: https://docs.tolt.com/errors#not_found
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
            required:
              - field
              - message
          description: >-
            One entry per offending field. Present on validation_error and
            invalid_reference.
      required:
        - success
        - message
        - code
        - doc_url
  headers:
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix time, in seconds, when the window resets.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    PayloadTooLarge:
      description: Request body exceeds 1 MB
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Request body exceeds 1 MB
            code: payload_too_large
            doc_url: https://docs.tolt.com/errors#payload_too_large
    RateLimited:
      description: The API key exceeded its rate limit
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            message: Too many requests. Retry after the window resets.
            code: rate_limited
            doc_url: https://docs.tolt.com/errors#rate_limited
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Tolt API key sent as a bearer token.

````

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