Introduction

Purpose of the DAP

The purpose of the Device Access Proxy (DAP) is to secure the communication between devices or services and Io-base.

The system relies on the distribution of authentication tokens which ensure that only approved devices can communicate with Io-base.

Service accounts

When requesting tokens, the device (or service) will use a service account.

(refer to section 3 : Device validation in Io-base).

There is a generic "default" service account, which should ideally be used for tests.

Before starting the procedure, we highly recommend that you request a service account dedicated to the use of the device (or service), to have better control over access rights on Io-base.

To request a DAP service account, contact support, specifying :

service account name
the rights required : read, write or read/write

In this way, if required, you can restrict rights to the metrics you need.

1 : Accessing the API query interface

The Io-base administration page opens.

Go to the Others/Console API menu.

Select the Device Authentication Proxy API, using the drop-down list at the top left of the screen.

Then, click on the Authorize button.

Enter the requested API key (contact your administrator if necessary), then click on Authorize.

You can now close the window by clicking on Close.

2 : Device registration

You can now register the new device.

Go to the Device Registration section, then click on POST / register.

Click on the “Try it out” button.

The screen below appears:

Complete the query by entering a name to identify your device. In our example : “device_documentation”.

Then, click on Execute.

A response with a Code 200 appears : the device has been successfully registered.

In the body of this response, keep the “device_code” parameter, as it will be useful when retrieving the access token (refer to section 4 : Access token retrieval).

Note : If a device with the same name has already been registered, registration is not possible and you will receive a response with a 403 code :

3 : Device validation in Io-base

This action must be carried out by an administrator.

Your device has been registered. It must now be validated by a user with a functional administrator role.

Here's the procedure for the administrator :

The Io-base administration page opens.

Go to the Administration/Services and devices menu.

You are redirected to the Devices management screen.

The device “device_documentation” is Waiting for validation.

In the Actions column, click on the Validate device button.

A window opens. In the drop-down list, choose the service account you wish to associate with the equipment.

Then click on Validate.

Note : It is preferable here to use a service account dedicated to the device rather than the default service account (refer to the Introduction).

The device is now validated.

For further information on the Devices portal, refer to our Devices management documentation.

4 : Access token retrieval

Once your device has been registered and validated by an administrator, it will be able to retrieve an access token, which enables to call Indaba APIs.

The token has a validity period, so once it has expired, a new one needs to be requested (refer to section 5 : Refreshing the token).

Follow the procedure below to retrieve an access token :

Access the API request interface again (refer to section 1: Accessing the API request interface).

Go to the Token management section, then click on Post / Token.

Complete the request by entering :

device_code : code sent in the body of the response received following your device registration request (refer to section 2 : Device registration).

client_id : the name you entered when registering your device, in our example “device_documentation”.

Then, click on Execute :

The following response appears :

In the response body, you can find :

the access_token, to call Indaba APIs:

the refresh token : to renew access to Io-base when the validity of the access token has expired

Note : in the Io-base Devices portal, the device status changes to “Token retrieved”.

Warning, for security purposes, token calls are only valid once.

If the same token is used twice, the device status switches to "failed".

In this case, the device must be deleted by an administrator in Io-base, and the procedure has to be repeated.

Note : If the device has not been validated by an administrator, the access token cannot be retrieved.

The response will be a code 425 : “Authorization Pending”.

Make sure the device is validated, then perform the operation again.

5 : Refresh token

The access token allocated to the equipment has a limited validity period. To continue communicating with Io-base, you'll need to renew this token.

To do this, return to the API request interface (refer to section 1: Accessing the API query interface).

In the Token Management section, click on Post/refresh.

Then, Try it out.

The following screen appears :

Complete the query by entering :

the “refresh_token”: which you can find in the body of the previous retrieved token response. In our case, here :

the “client_id” : the name you entered when registering the device, in our case “device_documentation” (refer to section 2 : Device registration)

The request body for our example will be :

Then, click on Execute :

The token has been refreshed and communication between the device and Io-base is ensured (response with code 200) :

In the response body, you can find :

the access_token, for calling Indaba APIs :

the refresh token : to renew communication between the device and Io-base when the new token expires

Warning, a “refresh_token” can only be used once.

If the same token is used twice, the device status switches to "failed".

In this case, the device must be deleted by an administrator in Io-base, and the procedure has to be repeated.