How to Use

The Authentication endpoint requires the Client ID and URI Scope (which can be located on the API Keys page), in addition to the Client Secret (displayed only at the time of API key creation). These inputs are used to generate a bearer token. The produced bearer token is unique to the Client ID and secret used and has a lifespan of 1 hour.

You can use the bearer token to access any endpoint in the BuildingMinds API. Within its 1-hour validity, this bearer token can be used for an unlimited number of calls. It also supports concurrent API calls to multiple BuildingMinds API endpoints.

Base URL

Base URL of BuildingMinds API: [https://api.dev.onbuildingminds.com/api/digitaltwinintegration]

Authentication

BuildingMinds REST API identifies 3rd party applications using API key based authorization. An application must pass BuildingMinds API key token in all requests in the request header authorization field. All requests should be made via Secure Sockets Layer (SSL).

API keys are unique and granted per BuildingMinds tenant. There key is valid for a specific time-period. After a key is expired, a new key must be generated.

🔐 Step 1: Create an API Key

Generate an API key from the BuildingMinds platform.

Visit the API Key management page:
https://cloud.onbuildingminds.com/#/admin-center/data-connection/api-keys
Click "+ Add" to create a new API key.
Provide a name and expiry date.
Copy the following credentials for Step 2:
1. Client ID
2. Scope URI
3. Client Secret

🔑 Step 2: Generate a Token via API

Send a POST request to:

https://login.microsoftonline.com/buildingminds.onmicrosoft.com/oauth2/v2.0/token

Request Headers

Content-Type: application/x-www-form-urlencoded

Request Body (URL-encoded)

The request body must be URL-encoded with the following parameters:

client_id: <your_client_id>
The unique identifier for your application registered in the Microsoft Identity platform.
scope: <scope_url>
The permission scope your app is requesting.
client_secret: <your_client_secret>
Secret associated with your application for authentication.
grant_type: client_credentials
Indicates that the app is requesting a token on its own behalf.

Sample Response

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "ext_expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6Ikp...<snipped>...LcjLkJbA"
}

📡 Step 3: Use the Access Token

After receiving the access_token from Step 2, include it in the Authorization header for all authenticated API requests.

Header Format

Authorization: Bearer <access_token>

Batch ID in response

When data is pushed in a single request using BuildingMinds API, a Batch ID is returned in case of a successful post.

User can use this Batch ID to see the status of the records pushed in this batch.

More details on that can be found on the Batch page.

Error handling

BuildingMinds API returns an HTTP status code for every request. A 2xx status code indicates success, whereas a 4xx or 5xx status code indicate an error.

Status Code	Description
200	Success
400	Validation error: An accompanying error message will explain further
401	Authentication error: The credentials were missing, incorrect or expired
403	Authentication error: The current authenticated user has no access to this resource
404	Invalid endpoint: The endpoint requested is invalid, or the resource requested, such as a meter, does not exist.
405	The HTTP method used for this endpoint is invalid.
429	Too many requests: The client has exceeded our rate limiting threshold.
5xx	An error has occurred within the server and the request couldn't be completed.
503	We're experiencing temporary server issues. Please try again.

When an API request fails, it will be accompanied by an explanatory message.
For example, an error might look like this: {code: 404, message: "Resource not found"}

API rate limit

BuildingMinds API has a rate limit of 100 API requests in 1 minute.