> ## 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.

# Connect a user you already identify

> For consumers that are themselves a provider: connects one of your own users without a browser. The provider comes from your API key, so it cannot be named in the body. The identifier is checked by listing the devices it yields; no devices means it is refused.



## OpenAPI

````yaml /api-docs/connect/openapi-connect.json post /connections
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:
  /connections:
    post:
      tags:
        - Connections
      summary: Connect a user you already identify
      description: >-
        For consumers that are themselves a provider: connects one of your own
        users without a browser. The provider comes from your API key, so it
        cannot be named in the body. The identifier is checked by listing the
        devices it yields; no devices means it is refused.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectConnectRequest'
      responses:
        '201':
          description: Connection created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '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'
        '403':
          description: >-
            This API key's consumer is not a provider, so it has no users of its
            own to connect.
          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:
    DirectConnectRequest:
      additionalProperties: false
      description: A consumer that is itself a provider, connecting one of its own users.
      properties:
        user_id:
          minLength: 1
          title: User Id
          type: string
          description: Your internal user ID.
        identifier:
          type: string
          title: Identifier
          description: >-
            The identifier NOX Energy uses to find this user's devices at your
            brand. Optional: when omitted, the `user_id` is used as the
            identifier.
      required:
        - user_id
      title: DirectConnectRequest
      type: object
    Connection:
      additionalProperties: false
      properties:
        connection_id:
          title: Connection Id
          type: string
        consumer_user_id:
          title: Consumer User Id
          type: string
        provider:
          title: Provider
          type: string
        credential_type:
          $ref: '#/components/schemas/CredentialType'
        device_ids:
          items:
            type: string
          title: Device Ids
          type: array
        needs_reauth:
          title: Needs Reauth
          type: boolean
        connected_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Connected At
      required:
        - connection_id
        - consumer_user_id
        - provider
        - credential_type
        - device_ids
        - needs_reauth
        - connected_at
      title: Connection
      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
    CredentialType:
      enum:
        - oauth
        - app_credentials
        - manufacturer_identifier
        - ean
      title: CredentialType
      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.