Convercus uses OAuth 2.0 with Keycloak for authentication.

ℹ️

Some legacy programs still use the old /auth/login endpoint. Please ask your account manager which authentication method your program uses.

OAuth

OAuth is the default authentication method. Most integrations should use the grant type client_credentials, which is the standard for machine-to-machine authentication.

The grant type password is used in special cases, for example, when a machine-to-machine user is also configured with username/password credentials. If you are not sure which method applies, please check with your account manager.

Quick start

1. Replace ENTERPROGRAM with your program name.
2. Use client credentials to request a token (default).
3. Send API requests with Authorization: Bearer <access_token>.
4. When expires_in nears, renew the access token (via refresh_token if available, or by requesting a new token).

Tip: Don’t hardcode expires_in. Renew proactively (e.g., at 80% of validity).

Parameter: ENTERPROGRAM

The value ENTERPROGRAM in the authentication URL must be replaced with the name of your loyalty program. The program name usually consists of three letters. Please ask your account manager if unsure.

• Example: If your program is called ABC, then the URL becomes: https://auth-staging.convercus.io/realms/abc-staging/protocol/openid-connect/token

Obtaining an Access token with Service Account and Client Secret (default)

This method uses grant_type=client_credentials.

http --form POST https://auth-staging.convercus.io/realms/ENTERPROGRAM-staging/protocol/openid-connect/token \
grant_type='client_credentials' \
client_id='machine-2-machine' \
client_secret='ENTERCLIENTSECRET' \
scope=openid

http --form POST https://auth.convercus.io/realms/ENTERPROGRAM/protocol/openid-connect/token \
grant_type='client_credentials' \
client_id='machine-2-machine' \
client_secret='ENTERCLIENTSECRET' \
scope=openid

ℹ️

All API-Calls will be logged with the username: service-account-machine-2-machine

Token Response

The response looks like this:

{
  "access_token": "eyJhbGc…",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "id_token": "eyJhbGci…",
  "not-before-policy": 0,
  "scope": "openid profile userId authorities organization partnerId sub Source email"
}

Field description:

ℹ️

The access token expires after 30 minutes. Repeat the same method to request a new access token.

Obtaining an Access token with Username, Password and Client Secret

This method uses grant_type='password' and is only applicable if your program is configured for username/password authentication.

http --form POST https://auth-staging.convercus.io/realms/ENTERPROGRAM-staging/protocol/openid-connect/token \
grant_type='password' \
client_id='machine-2-machine' \
client_secret='ENTERCLIENTSECRET' \
username='ENTERUSERNAME' \
password='ENTERPASSWORD' \
scope=openid

http --form POST https://auth.convercus.io/realms/ENTERPROGRAM/protocol/openid-connect/token \
grant_type='password' \
client_id='machine-2-machine' \
client_secret='ENTERCLIENTSECRET' \
username='ENTERUSERNAME' \
password='ENTERPASSWORD' \
scope=openid

Token Response

The response looks like this:

{
  "access_token": "eyJhbGc...",
  "expires_in": 1800,
  "refresh_expires_in": 604799,
  "refresh_token": "eyJhbGc...",
  "token_type": "Bearer",
  "id_token": "eyJhbGc...",
  "not-before-policy": 0,
  "session_state": "683...",
  "scope": "openid sub authorities Source profile organization email"
}

Field description:

ℹ️

The access token expires after 30 minutes. Use the refresh_token to obtain a new valid access_token.

Refresh Token

Method 1: No refresh_token

If your access_token has expired AND you have initially used grant_type=client_credentials to obtain your access_token, then use the same method as before to request a new access_token. See above.

http --form POST https://auth-staging.convercus.io/realms/ENTERPROGRAM-staging/protocol/openid-connect/token \
grant_type='client_credentials' \
client_id='machine-2-machine' \
client_secret='ENTERCLIENTSECRET' \
scope=openid

http --form POST https://auth.convercus.io/realms/ENTERPROGRAM/protocol/openid-connect/token \
grant_type=client_credentials \
client_id='machine-2-machine' \
client_secret='ENTERCLIENTSECRET' \
scope=openid

Method 2: Using a refresh_token

If your access_token has expired AND you have initially used grant_type=password to obtain your access_token, then use the refresh_token and grant_type=refresh_token to request a new access_token.

http --form POST https://auth-staging.convercus.io/realms/ENTERPROGRAM-staging/protocol/openid-connect/token \
grant_type='refresh_token' \
client_id='machine-2-machine' \
client_secret='ENTERCLIENTSECRET' \
refresh_token='ENTERREFRESHTOKEN' \
scope=openid

http --form POST https://auth.convercus.io/realms/ENTERPROGRAM/protocol/openid-connect/token \
grant_type='refresh_token' \
client_id='machine-2-machine' \
client_secret='ENTERCLIENTSECRET' \
refresh_token='ENTERREFRESHTOKEN' \
scope=openid

ℹ️

The refresh token expires after 1 week.

Legacy Authentication

Some older programs still use legacy authentication with /auth/login.

curl --location --request POST '{{api_url}}/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
  "org": "{{org}}",
  "userName": "{{userName}}",
  "password": "{{password}}"
}'

Parameters

⚠️ Note: The legacy token expires after 24 hours. To maintain a valid token, generate it regularly.