For Relatics to provide data to an external application or for external applications to synchronize data with Relatics, the external application must first authenticate to Relatics. Some external applications are programmable to access Relatics directly, while others need to use middleware.

Setup entrance key^*

1. In the overview with workspaces, click on Environment administration.
2. In the view Environment administration, click on the menu Application authentications.
3. In the table Relatics API keys for requests by external applications(s), click on New Relatics API key for requests by external applications(s). This opens a dialog where you can configure the entrance key.
4. For the field Name, provide a name representing the connected application or provided data.
5. Copy the Client ID. Make sure you (temporarily) save the Client ID for yourself so you can use it later.
6. Copy the Token endpoint URL. Ensure you (temporarily) save the URL for yourself so you can use it later.
7. Click Create. This will close the dialog and open a new dialog containing the client secret.
8. By closing the New client secret dialog, the Client Secret is copied to your clipboard. The generated client secret is only visible once; it cannot be read at a later moment. Make sure you store the client secret for yourself so you can use it later.

The entrance key has been created and is ready to be used by external applications to authorize themselves against the Relatics environment.

Authenticate an external application with a HTTP POST request

A HTTP POST request is required to authenticate the external application. The request consists of a token endpoint URL, headers, and a request body:

• You can submit the POST request to the Token endpoint URL. The URL can be found on the detail page of the Relatics API key and should look something like this:

https://authenticate.relatics.com/auth/realms/myenvironment/protocol/openid-connect/token

• The headers that need to be set are described in the table below:

• The request body contains a single parameter called “grant_type” with the value “client_credentials”.

grant_type=client_credentials

A successful request receives an access token in the response. With this token, you can synchronize or provide data with Relatics. Example of a response body:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ0NTd3LVFnOWZMazFwdm9qYUNCMW0wbTlma2FmbmNlSnpLNGt0Q0xBcTRvIn0.eyJleHAiOjE3MDQ0NjUzOTUsImlhdCI6MTcwNDQ2NDc5NSwianRpIjoiMTUxNDJhYmUtNDY5ZS00ZjVkLWI2ZGEtNmYxMmU4YWMyOTM5IiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay10c3Qtb3AucmVsYXRpY3MudGVjaC9hdXRoL3JlYWxtcy9wcm9kIiwic3ViIjoiOGQyMTFlMDMtZDZkNS00NmI5LWFhYzQtMGExZTQ2MDM1Yjk3IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiYzAwNWFlZjQtODhkNC00MmQ1LTkzN2UtMjkwZTRiYjE5NjYxIiwic2NvcGUiOiJEYXRhRXhjaGFuZ2UiLCJjbGllbnRIb3N0IjoiMTAuNDIuMTEuMTI4IiwiY2xpZW50QWRkcmVzcyI6IjEwLjQyLjExLjEyOCIsImNsaWVudF9pZCI6ImMwMDVhZWY0LTg4ZDQtNDJkNS05MzdlLTI5MGU0YmIxOTY2MSJ9.WYFNGUXKgPcO_Yhzx7l389musLyOK5wWwTOATYDuuSb7bvxx-IiU3HgFxH5G89wlFiX1JlR34ch0uxRZaDdV4fQjfmsQKNMEhlPxh0iV_QZS2RyBFgLlK9h2LsSmRLSCRAwxzpBTmuwuw9BEeCaalcrtI1Qfe2DcQK_m5h1QVkuzU3QULAFVR8zHauXP-mJ12s9nZaxDQPrPIGOmy7Dokm02jkGsY2THC0WtSRaTNFx1FnE_SQwMJjWxUenOlPVY4wPpCagfxzlXdYRE4rCSYXYhAcQ5YD5SpEEfpL3r17Vm9e-Agsd9p_F5VfAhJ7Q_PgfWXBmTjRXW5XQ725jd3g",
    "expires_in": 600,
    "not-before-policy": 1696859419,
    "refresh_expires_in": 0,
    "scope": "DataExchange",
    "token_type": "Bearer"
}

Authenticate an external application with built-in authorization

Applications with a built-in oAuth2.0 feature require the following information:

If successful, this method returns the access token in the response body. This token is needed to synchronize data with Relatics or to provide data to Relatics.

* In the environment, the administration role of your user must be set to administrator to enable this feature.