Who is this article for?

Administrators who need credentials to access Data API.

Admin Console access is required.

This guide walks you through getting the credentials you need to connect to an app’s data API. Your external system will need to authenticate using the OAuth 2.0 client credentials flow. Data API support is still rolling out and is only available for apps that offer one. We’ll share more as additional apps add support.

Enabling Data API access for a product instance

To enable data api access:

1. Sign in to the Ideagen portal.
2. Navigate to the Admin Console.
3. Go to the Security Centre.
4. Select Data API Configuration. Click Configure.
5. Under Client Applications, find the app instance (for example qpulseqms:FoodDrink) and set the toggle to enable.
6. Once enabled, the Client ID and Client Secret are shown. The secret is masked; select the reveal icon to view it when necessary.
7. Copy the Token endpoint, Scope, Client ID and Client Secret for use in your external system.

The Token endpoint, Authentication method and Scope are the same for every product instance in your organization. The Client ID and Client Secret are unique to each instance.

Requesting an access token

Your external system exchanges the client ID and secret for an access token, then sends that token with each data API request. Here’s what the exchange looks like:

1. Send a POST request to the token endpoint with:
   1. Header: Content-Type: application/x-www-form-urlencoded
   2. Header: Authorization: Basic <Base64(ClientID:ClientSecret)>
   3. Body: grant_type=client_credentials&scope=ideagen/data_api
2. The response contains an access_token and expires_in, which is how many seconds the token stays valid.
3. Include the token in the Authorization: Bearer <access_token> header on each Data API request.
4. When the token expires, request a new one by repeating step 1.

curl -X POST "<Token endpoint>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<Client ID>:<Client Secret>" \
  -d "grant_type=client_credentials&scope=ideagen/data_api"

Setting the token expiry duration

The token expiry duration controls how long each access token is valid. It defaults to 12 hours and can be set from 1 to 24 hours. It applies to every product instance in your organization. To set this:

1. On the Data API Configuration page, enter a value in Token expiry duration.
2. Select Save.

The new limit applies to tokens requested from then on. Tokens already issued keep their original lifetime.

This configuration does not issue refresh tokens. Your system must request a new access token before the current one expires. We recommend requesting a new token at about 80–90% of its lifetime, using the expires_in value from the token response rather than a fixed time. For example, with a 12-hour limit, request a new token after about 10 hours.

Turning off data API access

You can disable the credentials used for the data API when you no longer need it. To do this:

1. On the Data API Configuration page, find the app instance and toggle to disable the set of credentials.
2. Confirm that you want to proceed to turn off data API when prompted. The instance's client ID and secret are deleted and can't be recovered. 

Disabling a set of credentials does not end tokens already issued. Access tokens stay valid until they expire for up to your configured token expiry duration. No new tokens can be requested with the deleted credentials.

Replacing a secret. There is no separate rotate option. If you toggle to disable and enable the set of credentials again, a new set of client ID and secret is issued, and you must update your external system.

Frequently asked questions

Why don't I receive a refresh token?
The client credentials grant doesn't use refresh tokens. Request a new access token before the current one expires.

How do I know when my token expires?
Use the expires_in value in the token response. It shows the number of seconds the token is valid.

Can I set a different session limit for each product instance?
No. The session limit applies to every product instance in your organization.

I changed the session limit. Why is my current token only valid for the old duration?
The new limit only applies to tokens requested after the change. Request a new token to use the new limit.

My token request fails. What should I check?
Check that the client ID and secret are current, that the scope is ideagen/data_api, and the set of credentials is still enabled for the instance. If the credentials were disabled and re-enabled,  the old credentials no longer work.