API Authentication - HxGN Smart Build - Version 5.0 U2 (5.0.2) - Customization & Programming

HxGN Smart Build Insight API Help

Language
English
Product
HxGN Smart Build
Subproduct
Insight
Search by Category
Customization & Programming

Smart Build Insight uses Keycloak as the identity provider to authenticate users to access the published APIs. Keycloak supports authentication using the Authorization Code Flow with PKCE or Authorization Code Flow with Client Credentials methods, which validate only the authorized users and applications. For more information, refer Keycloak documentation.

How to access Smart Build Insight APIs

There are two ways in which you can access the APIs:

  • Use client credentials to obtain the access token

    This type of authentication is generally used for server-to-server interactions that run in the background.

    • Only a user with workspace admin role in Smart Build Insight can register the client application.

    • Use caution when sharing client_id and client_secret with any application, as your data might get compromised.

    • Never store the client_secret in plain text, instead store an encrypted or hashed version to reduce the chances of it getting exposed.

    Register the client application with Smart Build Insight

    1. Sign into Smart Build Insight with your workspace admin credentials.

    2. On the left bar, click Administrator Settings > Register applications.

    3. In the center panel, click Add new registration.

    4. In the Add new registration dialog box, specify name and description to easily identify the client application.

      After successful registration, Smart Build generates the client application credential details. You'll need these details to access the APIs.

    Follow these steps if the client application is already registered

    1. Sign into Smart Build Insight with your workspace admin credentials.

    2. On the left bar, click Administrator Settings > Register applications.

    3. Click the client application name to reveal the credential details.

    4. Using the credentials details, request the authorization server for an access token via Postman or any other REST API clients.

      POST <Authorization Server Token URL>

    5. Pass the following key-value pairs in the request headers:

      Key

      Value

      Authorization

      Basic <Base64 encoded credentials>

      content_type

      application/x-www-form-urlencoded

      For the Basic Authentication type of authorization, the client credentials such as client_ID and client_secret must be encoded in Base64. If you are using Postman, the API client automatically converts the credentials in base64 encoding.

      How to encode the client credentials in Base64?

      Base64 encoding scheme is used to encode binary data to store or transmit over media. It ensures that the data is not modified or corrupted during transport.

      You can use any programming language to encode the client credentials. Below are a few sample codes in Javascript, Java, C#, and Python, for your guidance.

      Javascript

      var base64_string = btoa(unescape(encodeURIComponent('client_id:client_secret')));

      C#

      byte[] stringToEncodeBytes = System.Text.Encoding.UTF8.GetBytes("client_id:client_secret");

      string base64_string = System.Convert.ToBase64String(stringToEncodeBytes);

      Java

      import java.util.Base64;

      String base64_string = Base64.getEncoder().encodeToString(("client_id:client_secret").getBytes());

      Python

      import base64

      string_to_encode = "client_id:client_secret"

      string_to_encode_bytes = string_to_encode.encode("ascii")

      base64_bytes = base64.b64encode(string_to_encode_bytes)

      base64_string = base64_bytes.decode("ascii")

    6. Pass the following key-value pairs in the request body:

      Key

      Value

      grant_type

      client_credentials

      user-agent

      Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36 Edg/112.0.1722.48

      After successful authentication, you will get the following response:

      {

      "access_token": "eyJhbG[...]1LQ",

      "expires_in": 3600,

      "refresh_expires_in": 0,

      "token_type": "Bearer",

      ...

      }

    7. Pass the access_token in the Authorization header as a key-value pair whenever you send a subsequent API request via Postman or any other REST API clients.

      Key

      Value

      Authorization

      Bearer <accessToken>

    The access token is valid only for one hour. When the token expires, resend the POST request to generate a new access token.

  • Leverage Smart Build Insight authentication client

    This approach requires successful authentication to the Smart Build Insight application without the need of any configuration.

    1. In the web-browser, type and load the Smart Build Insight authentication client using the following URL format: https://sbi.<SERVERNAME>.hxgnsmartbuild.com/authenticate/index.html

      Replace <SERVERNAME> with apac or emia depending on where your Smart Build Insight application is hosted.

    2. When prompted, enter your credentials.

    3. After successful authentication, click Copy Access Token.

      The API access token is copied to your clipboard.

    4. Pass the access token in the Authorization header as a key-value pair whenever you send an API request via Postman or any other REST API clients.

      Key

      Value

      Authorization

      Bearer <accessToken>

    The access token is valid for one hour. If the token expires, repeat the above steps to generate a new access token.

You must pass the access token in the authorization header while requesting any Smart Build Insight APIs, to access the metadata, annotations, and all other API endpoints except the Smart API Explorer documentation.

Smart Build Insight uses two-step verification or multi-factor authentication to keep your accounts more secure.