Authentication

Eliq APIs use OAuth 2.0 client credentials for authentication. Each integration is issued a dedicated OAuth client identity (client_id) that is set up in collaboration with your Eliq account manager and managed through the Client Admin Portal.

The access token obtained from the auth endpoint must be passed as a Bearer token in the Authorization header of all API requests. Client credentials and access tokens must never be stored insecurely or exposed to client-side applications (e.g. mobile or browser apps).

Getting started

Your client_id is provided by your Eliq account manager when your integration is set up. Client secrets are generated via the Client Admin API or by your account manager.

In the Client Admin Portal you can:

• View which APIs your client has access to
• Review the access types and scopes available per API
• Manage and rotate your client secrets

Multiple secrets are supported per client, allowing you to rotate secrets without downtime.

App token

Use this flow for server-to-server integrations where no end-user context is needed.

POST /oauth/token

{
  "grant_type": "client_credentials",
  "client_id": "utility-acme-backend",
  "client_secret": "{client_secret}",
  "aud": "data-management-api"
}

Field	Type	Description
grant_type	String	OAuth grant type. Use client_credentials for new tokens, or refresh_token to exchange a refresh token (see Refresh token section)
client_id	String	Your OAuth application identity, provided by your account manager
client_secret	String	Your client secret
aud	String	The API you are requesting access to (e.g. data-management-api, insights-api)
scope	String	Optional. Space-delimited scopes. Defaults to the scopes configured for your client

Delegated token

Use this flow to issue a token on behalf of a specific user. Required when the target API enforces user context (e.g. when calling the Insights API for a specific end user).

POST /oauth/token

{
  "grant_type": "client_credentials",
  "client_id": "utility-acme-frontend",
  "client_secret": "{client_secret}",
  "aud": "insights-api",
  "scope": "insights.read insights.write",
  "sub": "{user_id}",
  "sub_type": "user"
}

Field	Type	Description
grant_type	String	Always client_credentials
client_id	String	Your OAuth application identity
client_secret	String	Your client secret
aud	String	The API you are requesting access to
scope	String	Optional. Space-delimited scopes
sub	String	The ID of the user the token is issued on behalf of
sub_type	String	Type of subject — typically user
issue_refresh_token	Boolean	Optional. Set to true to receive a refresh token alongside the access token

Token response

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600
}

For delegated tokens with issue_refresh_token: true, the response also includes:

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eliq_rt_...",
  "refresh_token_expires_in": 2592000
}

Refresh token

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

POST /oauth/token

{
  "grant_type": "refresh_token",
  "refresh_token": "{refresh_token}"
}

Token verification

Tokens are signed with asymmetric keys. The public key set is available at GET https://auth-api.eliq.com/.well-known/jwks.json. The full OpenID Connect discovery document is available at GET https://auth-api.eliq.com/.well-known/openid-configuration.

Endpoints

Environment	URL
Production	https://auth-api.eliq.com
UAT	https://auth-api-uat.eliq.com

Full API reference: developer.eliq.com/api-reference/auth-api

Legacy authentication

If your integration uses a numeric client_id (Utility ClientId), your existing setup continues to work without any changes. Contact your account manager to discuss migrating to the current authentication model.