Client API section

• Applies to: All Board Cloud subscriptions

WHAT: Introduction to Client API users

Client API users allow for the configuration and customization of how the Board ecosystem is integrated into other third-party software environments.

Once the initial configuration has been created, the external environment will be able to read and manipulate data from Board and to execute specific operations on its platforms.

For example, through an HTTPS requests, it is possible to obtain lists of Entities, Cubes, Relationships, or Entity members in JSON format. It is also possible to execute a Layout, search for a Capsule, execute a Database procedure, and perform a full text search.

Client API users cannot be imported via CSV file. They can be manually imported from a Board platform, once you associate it with the Subscription Hub.

HOW: Client API configuration

To configure the Client API, proceed as follows:

1. Click on "CLIENT API" and fill in all required fields, marked with a *: Client ID, New client secret, and Confirm client secret fields
   The Client ID and the client secret are essentially a username and a password that the external client will use to obtain an access token from the Subscription Hub. The request must comply to OAuth2 client credentials flow specifications.
   Once that token has been provided, it'll have to be included in the API requests' header to access Board's resources.

   Tokens are valid for 8400 seconds (2.3 hours) from creation and will expire automatically after that time. If a Client API user is deleted, any API token created by that user account is deprovisioned at the same time. If a Client API user is only disabled, any API token created by that user account will continue to work until its expiration, but it is not possible to create a new token until the user is enabled again.

2. Choose the appropriate "Culture" option to apply a specific date and time format to API responses. Leave it blank to apply the default date and time format

3. From the License dropdown menu, select the License type you'd like to assign to the client API, just like you'd do when adding a new user account.

   The available License types may vary, depending on your Cloud Subscription. To know more about Board Licenses please visit this page.

   When the "Disabled" checkbox is ticked, the external client won't be able to make API requests using the configured credentials and its license will be available to assign to other user accounts

4. If you are creating the client API to be used with Board's SCIM API service, tick the “enable SCIM endpoint” option

5. In the Platform authorization table, select a Role, assign a License type and, if applicable, tick the "Admin" checkbox: if checked, the external client will be able to launch business critical procedures, as per your Board platforms configuration. You will need to set those attributes for each listed Board platform you want to give the external client access to.
   To know more about the Platform authorization table, please see this paragraph

6. Set API permissions by ticking the desired checkboxes. You will need to do this for each listed Board platform you want to give the external client access to (see the Board Public APIs section for more information).

7. Click "SAVE" to create the system user and start using Board's public APIs.

To know more about available APIs, please see the Board Public APIs section and the SCIM API section.

Client APIs overview

The API Queries have to be configured in all Board platforms, under the "API queries" section of each Data model you want the APIs to work with.

Once you've created the necessary Client API user, an authorization token must be generated before making any request.

The token returned from this request must be used to manage the authentication in the API requests.

The authentication must comply with OAuth2 client credentials flow specifications.

To obtain the authorization token, you need to set the following additional parameters:

• Grant Type: "Client Credentials"

• Access Token URL: https://your-subscription-hub-url/connect/token

• Scope: "public-api"

• Client Authentication: "Send client credentials in body"

Client API users don't consume any Board license, but Roles applied in the "Platform authorization" table are always respected.

ApiQuery requests limits

ApiQuery requests are free up to 500 requests per day and 10 requests per second. This limit can be increased with an additional license. If you need an increase to your quota, please contact your Board Customer Success Manager or Key Account Manager.
Please note that custom quotas are only available for Cloud subscriptions.

API authorization in Swagger

You can perform an API Client authorization in the Swagger interface, which allows you to test Board public API queries directly from Swagger. The authentication supports only the OAuth2 client credentials flow.

To authenticate, proceed as follows:

1. From the Board public API documentation page in Swagger, click on the "Expand operations" of the desired public API endpoint and then click on the red circular button with the exclamation point to open the authorization pop-up window.

   You can access the API documentation page from the API queries page of the desired Data model

   

2. Select "Request body" from the type field

3. Enter the Client ID of the required Client API in the "ClientId" field

4. Enter the Client Secret of the required Client API in the "Secret" field

5. Enable the "public-api" scope option

6. Click on "Authorize" to authenticate. The red button with the exclamation point will become blue after a successful authentication. If that happens, you can try out the API queries directly from the Swagger page.