> ## 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 a link session

> Creates a single-use link to send your user to. Pass a `provider` to connect that provider directly, or a `connection_type` (for example `utility`) to let the user choose one. The link expires after 60 minutes.



## OpenAPI

````yaml /api-docs/connect/openapi-connect.json post /link
openapi: 3.1.0
info:
  title: NOX Connections API
  version: 1.0.0
  description: >-
    Connect a user's account at a provider (a device brand or a utility) to NOX
    Energy, and manage that access.
servers:
  - url: https://api.connect.nox.energy/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Connections
    description: Creating, listing and revoking connections.
  - name: Households
    description: The dwelling a person's connections belong to.
paths:
  /link:
    post:
      tags:
        - Connections
      summary: Create a link session
      description: >-
        Creates a single-use link to send your user to. Pass a `provider` to
        connect that provider directly, or a `connection_type` (for example
        `utility`) to let the user choose one. The link expires after 60
        minutes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkRequest'
      responses:
        '201':
          description: Session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkResponse'
        '400':
          description: >-
            The request was rejected; `error` says which field, rule or
            provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or unknown API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: A bug on our side; `code` is `unexpected`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKey: []
components:
  schemas:
    LinkRequest:
      additionalProperties: false
      properties:
        user_id:
          minLength: 1
          title: User Id
          type: string
          description: Your internal user ID.
        redirect_url:
          format: uri
          maxLength: 2083
          minLength: 1
          title: Redirect Url
          type: string
        provider:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Provider
        connection_type:
          anyOf:
            - $ref: '#/components/schemas/ConnectionType'
            - type: 'null'
          default: null
        language:
          default: nl
          enum:
            - nl
            - en
            - fr
            - es
          title: Language
          type: string
      required:
        - user_id
        - redirect_url
      title: LinkRequest
      type: object
    LinkResponse:
      additionalProperties: false
      properties:
        link_token:
          title: Link Token
          type: string
        link_url:
          title: Link Url
          type: string
      required:
        - link_token
        - link_url
      title: LinkResponse
      type: object
    Error:
      type: object
      properties:
        error:
          type: string
          description: What went wrong, in full.
        code:
          $ref: '#/components/schemas/ConnectFailureCode'
          description: >-
            Present when the failure has one: the same closed set the connect UI
            translates.
      required:
        - error
    ConnectionType:
      enum:
        - oem
        - oem.hp
        - oem.pv
        - utility
      title: ConnectionType
      type: string
    ConnectFailureCode:
      description: Ported from what the legacy authenticator-api tells users.
      enum:
        - no_devices
        - unsupported_device
        - invalid_credentials
        - unsupported_country
        - not_account_owner
        - multiple_users
        - missing_site_id
        - invalid_ean
        - invalid_site_id
        - onboarding_failed
        - registration_failed
        - missing_permissions
        - hybrid_inverter_not_allowed
        - session_not_found
        - session_expired
        - authorization_spent
        - provider_unavailable
        - rate_limited
        - invalid_request
        - unexpected
      title: ConnectFailureCode
      type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your consumer API key.

````

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