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

# Create supplier link session

> Create a new link session to connect a user of an energy supplier, with the intend to authenticate with the device manufacturer. The returned `link_url` should be used to redirect the end-user to the NOX Authenticator UI.



## OpenAPI

````yaml /api-docs/supplier-integration/openapi-supplier-auth-v2.json post /supplier/link-sessions
openapi: 3.0.3
info:
  title: NOX Authenticator API — Supplier
  description: Endpoints for energy suppliers to create link sessions.
  version: 2.0.0
  contact:
    name: NOX Energy
servers:
  - url: https://auth.nox.energy/v2
    description: Production
security: []
tags:
  - name: Supplier
    description: Endpoints for energy suppliers to create link sessions.
paths:
  /supplier/link-sessions:
    post:
      tags:
        - Supplier
      summary: Create supplier link session
      description: >-
        Create a new link session to connect a user of an energy supplier, with
        the intend to authenticate with the device manufacturer. The returned
        `link_url` should be used to redirect the end-user to the NOX
        Authenticator UI.
      operationId: createSupplierLinkSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSupplierLinkSessionRequest'
      responses:
        '201':
          description: Link session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSupplierLinkSessionResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: 'Missing required fields: user_id, redirect_url'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateSupplierLinkSessionRequest:
      type: object
      required:
        - user_id
        - redirect_url
        - asset_type
      properties:
        user_id:
          type: string
          description: The supplier's internal user ID for the end-user.
          example: supplier_user_id_123
        brand:
          $ref: '#/components/schemas/Brand'
          nullable: true
          description: >-
            Optionally pre-select a manufacturer brand. Must be a valid brand
            for the given `asset_type`.
        language:
          $ref: '#/components/schemas/Language'
        asset_type:
          $ref: '#/components/schemas/AssetType'
          description: >-
            Device category for this link session. Determines which brands are
            available.
        redirect_url:
          type: string
          format: uri
          description: Callback URL where the user is redirected after completing the flow.
          example: https://your-app.com/callback
    CreateSupplierLinkSessionResponse:
      type: object
      required:
        - link_url
        - link_token
        - supplier
        - supplier_user_id
        - redirect_url
        - language
        - asset_type
        - created_at
        - expires_at
      properties:
        link_url:
          type: string
          format: uri
          description: Full URL to redirect the end-user to the NOX Authenticator UI.
          example: https://auth.nox.energy/ui?token=abc123&language=nl
        link_token:
          type: string
          description: Unique token identifying this link session.
          example: abc123
        brand:
          $ref: '#/components/schemas/Brand'
          nullable: true
          description: Pre-selected brand, if provided.
        language:
          $ref: '#/components/schemas/Language'
        asset_type:
          $ref: '#/components/schemas/AssetType'
        redirect_url:
          type: string
          format: uri
          description: The redirect URL that was provided.
          example: https://your-app.com/callback
        supplier:
          type: string
          description: Name of the supplier (resolved from API key).
          example: Acme Energy
        supplier_user_id:
          type: string
          description: The supplier's user ID.
          example: supplier_user_id_123
        completed_at:
          type: integer
          description: >-
            Unix timestamp when the session was completed. Always `null` on
            creation.
          nullable: true
        created_at:
          type: integer
          description: Unix timestamp when the session was created.
          example: 1703123456
        expires_at:
          type: integer
          description: Unix timestamp when the session expires (10 minutes after creation).
          example: 1703124056
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
    Brand:
      type: string
      enum:
        - alpha-ess
        - alpha-innotec
        - apsystems
        - atlantic
        - bosch
        - buderus
        - bulex
        - ctc
        - daikin
        - dewarmte
        - deye
        - enphase
        - felicity-solar
        - fox-ess
        - fronius
        - fujitsu
        - goodwe
        - growatt
        - hitachi
        - hoymiles
        - huawei
        - hyxipower
        - ilumen
        - ivt
        - ja-solar
        - jaspi
        - jinkosolar
        - kostal
        - lg
        - longi
        - midea
        - mitsubishi
        - nibe
        - panasonic
        - saj
        - samsung
        - saunier-duval
        - sanyo
        - sigenergy
        - sma
        - sofar
        - solaredge
        - solarman
        - solax
        - solis
        - solarwatt
        - sungrow
        - sunpower
        - talesun
        - thermia
        - thermor
        - toshiba
        - trinasolar
        - vaillant
        - victron
        - viessmann
      description: Manufacturer brand.
    Language:
      type: string
      enum:
        - nl
        - en
        - fr
        - es
      default: nl
      description: Language for the Authenticator UI.
    AssetType:
      type: string
      enum:
        - hp
        - pv
      description: 'Device category: `hp` (heat pump) or `pv` (PV solar inverter).'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key assigned to the supplier.

````