This guide explains how to access IOTFactory platform data via API.

You will learn how to:

• Create an API key and define access rights for a user group.
• Authenticate users using an API key or token.
• Use API endpoints to retrieve assets and their data.

Prerequisite: API access requires authentication and authorization.

1. In the Account Manager, go to user group.
2. Create a new group.
3. Define access rights per API for the group.

1. In the Account Manager, navigate to settings > Global.
2. Select the API Keys entry.
3. Click Add API Key.
4. Assign the key to the user group you created.
5. Save and copy the generated API key (it will not be displayed again).

⚠️ Important: Store this key securely. It is required for authentication.

To authenticate a user, use the following endpoint:

1. Method: POST
2. URL: https://report.iotfactory.eu/login
3. Required Data (JSON format):

json
{
  "email": "your@email.com",
  "password": "your_password"
}

Success Response: A JSON object containing an authentication token in `res.data._id`.

Example:


json
{
  "data": {
    "_id": "your_authentication_token"
  }
}

1. Store the token in your application (e.g., HTML5 Local Storage).
2. For all authenticated requests, include the token in the HTTP header:

http
Authorization: Bearer your_authentication_token

To log out, simply delete the stored token from your application.

1. Security: Never share your API key or token.
2. Storage: Use secure mechanisms (e.g., environment variables, encrypted Local Storage).
3. Error Handling: Always check the API response to handle failures (e.g., expired token).

This use case shows you the APIs you can use to obtain a list of all the assets in your account, obtain the details of an asset based on its identifier and retrieve data from connected devices.

List all assets for the currently logged-in user.

GET ASSETS https://report.iotfactory.eu/api/assets?fields=_id&fields=name

Request headers

For all authenticated requests, include the token in the HTTP header:

http
Authorization: Bearer your_authentication_token

URL Variables

Get one asset by ID

GET ASSET https://report.iotfactory.eu/api/assets/{id}

Request headers

For all authenticated requests, include the token in the HTTP header:

http
Authorization: Bearer your_authentication_token

URL Params

—

URL Variables

GET ASSET https://report.iotfactory.eu/api/assets/{id}/measurements

URL Params

—

URL Variables

Devices, smart devices or static lists can be attached to an asset. The identifiers of these objects can be found in the corresponding table of an asset.

Ex: Get the last ten weekly smart measurements of a smart devices (_id:6513e6769a0d12001268d169) attached to an asset(_id:6508132813019d0012630749) after the 16/11/2023 10pm UTC

    https://report.iotfactory.eu/api/assets/6508132813019d0012630749/measurements?device=6513e6769a0d12001268d169&type=Occupied (first)&step=weekly&limit=10&after=2023-11-16T22:00:00.000Z
    

Result:

    {
  "data": [
      {
          "_id": "65aef1c2d6c621996407a92c",
          "smartdevice": {
              "id": "6513e6769a0d12001268d16c",
              "team": "1ha4pei7n.hp",
              "name": "Desk occupied"
          },
          "timestamp": 1705878000000,
          "updatedAt": "2024-01-23T14:36:18.131Z",
          "device": {},
          "staticList": {},
          "measurements": [
              {
                  "type": "Occupied (first)",
                  "value": 0,
                  "before": 1705878000000,
                  "at": "2024-01-21T22:55:00.000Z",
                  "unit": "",
                  "cache": true
              }
          ]
      },
      
      ...
      
      {
          "_id": "6573242b70f14a87dbaf0079",
          "smartdevice": {
              "id": "6513e6769a0d12001268d16c",
              "team": "1ha4pei7n.hp",
              "name": "Desk occupied"
          },
          "timestamp": 1700434800000,
          "updatedAt": "2023-12-08T14:14:35.531Z",
          "device": {},
          "staticList": {},
          "measurements": [
              {
                  "type": "Occupied (first)",
                  "value": 0,
                  "before": 1700434800000,
                  "at": "2023-11-19T22:55:00.000Z",
                  "unit": "",
                  "cache": false
              }
          ]
      }
  ],
  "pages": 1,
  "parent": {
      "_id": "6508132813019d0012630743",
      "name": "Anderlecht"
  },
  "recordsFiltered": 10
  }