Eliq OAUTH API

openapi: 3.2.0
info:
  title: Eliq auth OAUTH API
  version: 2.0.0
  description: '# Eliq auth API


    Used to obtain access tokens for Eliq APIs, most commonly the Eliq data management API and Eliq insights API.'
servers:
- url: https://auth-api.eliq.com
  description: Production
- url: https://auth-api-uat.eliq.com
  description: UAT
tags:
- name: OAuth
paths:
  /oauth/token:
    parameters: []
    post:
      summary: Request a token
      operationId: post-oauth-token
      description: 'Create an Eliq access token using OAuth 2.0 client credentials.


        The `client_id` field determines which flow is used:

        - **Non-numeric string** → Auth v2

        - **Numeric string** → Legacy v1 (see legacy section)

        - **`grant_type: refresh_token`** → Token refresh (no `client_id` needed)


        ---


        ### App token


        Issues a machine-to-machine token scoped to a specific API. Use this for server-to-server integrations where no end-user context is required.


        ```json

        {

        "grant_type": "client_credentials",

        "client_id": "utility-acme-backend",

        "client_secret": "eliq_...",

        "aud": "data-management-api",

        "scope": "data.read data.write"

        }

        ```


        ---


        ### Delegated token


        Issues a token on behalf of a subject (e.g. a specific user or location). Required when the target API enforces subject context.


        ```json

        {

        "grant_type": "client_credentials",

        "client_id": "utility-acme-frontend",

        "client_secret": "eliq_...",

        "aud": "insights-api",

        "scope": "insights.read insights.write",

        "sub": "12345",

        "sub_type": "user"

        }

        ```


        Set `"issue_refresh_token": true` to also receive a refresh token in the response.


        ---


        ### Token refresh


        Exchange a refresh token for a new access token without re-authenticating.


        ```json

        {

        "grant_type": "refresh_token",

        "refresh_token": "eliq_rt_..."

        }

        ```


        ---


        ### Legacy v1


        If your `client_id` is a numeric Utility ClientId, use this flow. No other fields are supported.


        ```json

        {

        "grant_type": "client_credentials",

        "client_id": "1234567890",

        "client_secret": "..."

        }

        ```'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/token-request'
            examples:
              app-token:
                summary: App token
                value:
                  grant_type: client_credentials
                  client_id: utility-acme-backend
                  client_secret: eliq_Hcjr4OLI91flAP-o8e4G5-W1nwDxg8PjSCIfHo2cgMo
                  aud: data-management-api
                  scope: data.read data.write
              delegated-token:
                summary: Delegated token
                value:
                  grant_type: client_credentials
                  client_id: utility-acme-frontend
                  client_secret: eliq_Hcjr4OLI91flAP-o8e4G5-W1nwDxg8PjSCIfHo2cgMo
                  aud: insights-api
                  scope: insights.read insights.write
                  sub: '12345'
                  sub_type: user
                  issue_refresh_token: true
              refresh-token:
                summary: Refresh token
                value:
                  grant_type: refresh_token
                  refresh_token: eliq_rt_RGjWlUx0s3yursEPHSf3Sg36bb1UqbasJ85QoCt0XyxW2oinIfNnbvlirs2u6L-z70CN0zQwJJ1psdVEUD2R-w
              legacy-v1:
                summary: Legacy v1 (numeric client_id)
                value:
                  grant_type: client_credentials
                  client_id: '1234567890'
                  client_secret: VFGJIJz49ZdYfif/NGdD+neVtpx7YScWlh0Rp2oMZpU=
      responses:
        '200':
          description: Token issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/token-response'
              examples:
                app-token:
                  summary: App token response
                  value:
                    access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                    token_type: Bearer
                    expires_in: 3600
                delegated-token:
                  summary: Delegated token response (includes refresh token)
                  value:
                    access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                    token_type: Bearer
                    expires_in: 3600
                    refresh_token: eliq_rt_RGjWlUx0s3yursEPHSf3Sg36bb1UqbasJ85QoCt0XyxW2oinIfNnbvlirs2u6L-z70CN0zQwJJ1psdVEUD2R-w
                    refresh_token_expires_in: 2592000
        '400':
          description: Bad Request — invalid or missing parameters
        '401':
          description: Unauthorized — invalid client credentials or refresh token
      tags:
      - OAuth
components:
  schemas:
    token-request:
      title: Token request
      type: object
      required:
      - grant_type
      properties:
        grant_type:
          type: string
          description: 'The OAuth grant type.

            - `client_credentials` — issue a new app or delegated token

            - `refresh_token` — exchange a refresh token for a new access token'
          enum:
          - client_credentials
          - refresh_token
          example: client_credentials
        client_id:
          type: string
          description: 'The OAuth application identity. A non-numeric string, e.g. `utility-acme-backend` (for data-management-api)

            or `utility-acme-frontend` (for insights-api).

            Required for `client_credentials` grant.'
          example: utility-acme-backend
        client_secret:
          type: string
          description: The client secret. Required for `client_credentials` grant.
          example: eliq_Hcjr4OLI91flAP-o8e4G5-W1nwDxg8PjSCIfHo2cgMo
        aud:
          type: string
          description: 'The target API the token should be scoped to (e.g. `data-management-api`, `insights-api`).

            Required for Auth v2 flows.'
          example: data-management-api
        scope:
          type: string
          description: 'Space-delimited list of requested scopes. Optional — if omitted, the default scopes

            configured for the client are used.'
          example: data.read data.write
        sub:
          type: string
          description: 'The subject identifier on whose behalf the token is issued (e.g. a user ID or location ID).

            Required for delegated flows. Must be accompanied by `sub_type`.

            The subject is not verified during token creation but will be enforced by the target API.'
          example: '12345'
        sub_type:
          type: string
          description: 'The type of subject referenced by `sub` (e.g. `user`, `location`).

            Required when `sub` is set.'
          example: user
        issue_refresh_token:
          type: boolean
          description: 'Whether to include a refresh token in the response. Applies to delegated flows only.

            May be denied by server policy regardless of this value.'
          example: true
        refresh_token:
          type: string
          description: The refresh token to exchange. Required when `grant_type` is `refresh_token`.
          example: eliq_rt_RGjWlUx0s3yursEPHSf3Sg36bb1UqbasJ85QoCt0XyxW2oinIfNnbvlirs2u6L-z70CN0zQwJJ1psdVEUD2R-w
      examples:
      - grant_type: client_credentials
        client_id: utility-acme-backend
        client_secret: eliq_Hcjr4OLI91flAP-o8e4G5-W1nwDxg8PjSCIfHo2cgMo
        aud: data-management-api
    token-response:
      title: Token response
      description: Response returned on successful token creation.
      type: object
      required:
      - access_token
      - token_type
      - expires_in
      properties:
        access_token:
          type: string
          description: The issued JWT access token.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        token_type:
          type: string
          description: Always `Bearer`.
          example: Bearer
        expires_in:
          type: number
          description: Seconds until the access token expires.
          example: 3600
        refresh_token:
          type: string
          description: 'A refresh token for obtaining a new access token. Only present in delegated token responses

            when a refresh token was requested and approved.'
          example: eliq_rt_RGjWlUx0s3yursEPHSf3Sg36bb1UqbasJ85QoCt0XyxW2oinIfNnbvlirs2u6L-z70CN0zQwJJ1psdVEUD2R-w
        refresh_token_expires_in:
          type: number
          description: Seconds until the refresh token expires. Only present when `refresh_token` is included.
          example: 2592000
      examples:
      - access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
        token_type: Bearer
        expires_in: 3600