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