Authenticate an external application to use custom application integrations

Authenticate an external application to use custom application integrations

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:
Key name Value Description
Content-Type string application/x-www-form-URL-encoded
Authorization string “Basic {authenticateCode}”

Where:

  • authenticateCode: a base64 encoded string of the Client ID and Client Secret separated with a colon.

Example unencoded authenticateCode :
c005aef4-88d4-42d5-937e-290e4bb19661:c5229a8e-0dff-4270-80a6-a5a47267e7f7-ec85c647-d089-4fda-87d3-89866ac5fefe-80090b3f-cc2c-4c01-8e34-c3c83c145368

Example header value (with encoded authenticateCode):
Basic  YzAwNWFlZjQtODhkNC00MmQ1LTkzN2UtMjkwZTRiYjE5NjYxOmM1MjI5YThlLTBkZmYtNDI3MC04MGE2LWE1YTQ3MjY3ZTdmNy1lYzg1YzY0Ny1kMDg5LTRmZGEtODdkMy04OTg2NmFjNWZlZmUtODAwOTBiM2YtY2MyYy00YzAxLThlMzQtYzNjODNjMTQ1MzY4

Accept string */*
Cache-Control string no-cache
Accept-Encoding string gzip, deflate, br
  • 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:

Setting Value
Type OAuth 2.0
Add authorization data to Request Headers
Grant type Client Credentials
Access Token URL This URL can be found on the detail page of the entrance key and should look something like this:

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

Client ID Generated at the creation of the entrance key. It can be retrieved at the details of the entrance key.
Client Secret Generated at the creation of the entrance key.

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.
Back
Schakel JavaScript in je browser in om dit formulier in te vullen.

Download the whitepaper

Schakel JavaScript in je browser in om dit formulier in te vullen.

Download the whitepaper

Request a demo

Fill in the below information and we will contact you to schedule a demo.

Schakel JavaScript in je browser in om dit formulier in te vullen.
We will use this information to contact you.
Schakel JavaScript in je browser in om dit formulier in te vullen.
Schakel JavaScript in je browser in om dit formulier in te vullen.
Addresss

Neem contact op

Vul ons formulier in en een van de Relatics medewerkers neemt zo snel mogelijk contact met u op. Liever telefonisch contact? Bel ons op +31 (0) 180 413 047.
Schakel JavaScript in je browser in om dit formulier in te vullen.