Skip to main content

Documentation Portal

Update API integrations

The 2022.R1.0 release has a completely new security backend. This also has some implications in case you are using the TrendMiner APIs to interact with other applications:

  • The client id/client secret pair you used before will no longer work. As of this release you can generate your own client id/client secret pair in ConfigHub.

  • Basic authentication purely with username and password is not supported anymore.

All requests to the web API require authentication. This is achieved by sending a valid Bearer access token in the request headers. Request tokens are obtained using OAuth2.0. Requests to the API can be done authenticated as your client or authenticated as a specific user.

Authenticate as a client (with client id/client secret)

APIs that do not require a user with a specific role can be executed when being authenticated through a client ID and secret (e.g. batch indexing, searches, …). To execute admin only APIs (like monitoring health check) or to perform user-specific actions (like actions on a user’s work items), you need to be authenticated as a user.

When authenticating as a client, please make sure the client is assigned to the proper ACLs in ConfigHub. Clients can be assigned to an ACL similar to regular users and groups.

Example of fetching a token via python:

import requests 
base_url = 'https://myurl.net'
client_id = 'client1'
client_secret = '9c97759a-2cfe-4d22-a236-2fe13e5eca60' 

response = requests.post(base_url + '/auth/realms/trendminer/protocol/openid-connect/token',                         
                         auth = (client_id, client_secret),                         
                         data = {'grant_type':'client_credentials'}) 

if response.status_code in [200]:    
   access_token = response.json()["access_token"]    
   print(access_token)
else:    
   print(response.json()['error_description'])

The value in "access_token" in the response can be used as bearer token in the header to TrendMiner endpoints.

A new token needs to be fetched when the token expires after 5 minutes.

Tip

Also the TrendMiner support scripts are affected and updated in this release. Please find the latest version of the support scripts (e.g. batch indexing) on our download site.

Authenticate as a user

Note

Authentication as a user is only supported for local users, not for user accounts managed by SAML or LDAP.

For user based authentication it is not required to add the used client id to ACLs in ConfigHub. The user specific ACLs will be used instead for determining the correct permissions.

Example of fetching a token via python:

import requests 
base_url = 'https://myurl.net'
client_id = 'client1'
client_secret = '9c97759a-2cfe-4d22-a236-2fe13e5eca60' 
username = 'myUsername'
password = 'myPassword'

response = requests.post(base_url + '/auth/realms/trendminer/protocol/openid-connect/token',                         
                         auth = (client_id, client_secret),                         
                         data = {'grant_type':'password',
                                 'username':username,
                                 'password':password }) 

if response.status_code in [200]:    
   access_token = response.json()["access_token"]    
   print(access_token)
else:    
   print(response.json()['error_description'])

The value in "access_token" in the response can be used as bearer token in the header to TrendMiner endpoints.

A new token needs to be fetched when the token expires after 5 minutes.

In this section: