Third Party Integration - API

The Datavault Builder offers possibilities to be integrated within your companies IT-Landscape. Please check the knowledge base for a detailed API Documentation.

Every action in the Datavault Builder calls a REST-API. Therefore, every action you can perform within the GUI, you can as well perform directly by calling the REST-API.

Using a standard user

One possiblity, is to write a script which will at the beginning:

  1. Login to the Datavault Builder just as you do with the User Interface by calling the login-API. Call-Body:

    {username: "standard_username",
password: "Password"}

  2. This API will then return you an authentication-token, which needs to be sent with each and every request. Response-Body:

    {"token":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiZHZiX2FkbWluIiwidXNlcm5hbWUiOiJkZW1vIiwiZXhwIjoxNTc0MTc0MTg1fQ.U3Kl2aIQHuwc7YxQVtjzOugsyuGn1l7Cnb18yAT5W0qAzWJ8AwCJvvOiIixybvVHtA0quY0BNlA4Ka_BpVroLA","token_timeout":300}

Note

For security reasons, this tokens timeout after a certain while. Therefore, when writing your script, make sure to call renewToken before the login expires.

Using a technical user

Another possibility is to make use of a technical user. A technical user is a role, which after login will receive an access Token without an expiration. With this long-living Tokens you can then create your REST-API calls, without having to worry about token-timeouts.

  1. Prerequisite

    To keep the token stable even when restarting the Datavault Builder, you need to define a docker secret in the docker-compose file called jwt_secret. By default, the jwt_secret is assigned randomly on each api start, leading to different tokens generated.

    api:
    secrets:
    - jwt_secret

    Note

    The jwt_secret has to be at least 64 characters long.

    Hint

    Finally, when you added the secret in the api part, you have to assign a file (where the secret is located) to this variable in the secret part as well:

    secrets:
    jwt_secret:
        file: secrets/jwt_secret.txt
  2. Create technical user

    Then a technical user can be created by calling the function dvb_core.f_create_user in the command line. Make sure to set the parameter non_expiring_token to TRUE.

    ../_images/createTechUser.png
  3. Call the login-API

    To get your non-expiring token.

    Call-Body:

    {username: "technical_username",
password: "SuperPassword"}

    Response-Body:

    {"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlY2huaWNhbF91c2VybmFtZSIsInJvbGUiOiJkdmJfZGV2In0.Pc_yrMuwUnZoP2iZD_QA93BB_yTgWHy4XUoglf7DJco"}
  4. Use Token

    This token can now be used in the header of any REST-Call made to the Datavault Builder API, without requiring a fresh login.

    It is recommended to still expire this tokens after a while. To do so, you can change the jwt_secret in the docker-compose file and restart the API (can be done by calling docker-compose up -d). Thereby all previously received tokens are invalidated.