2: Authenticating and configuring functions

Authenticating

Before you can use the ekey bionyx API, you have to authenticate to it.
For this you need a valid ekey bionyx user ID.

To authenticate against our API you have to use OAuth 2.0. A good way of doing this is using the Auth code flow. Information about this flow can be found at multiple sources, for instance at Microsoft’s documentation.

Using that flow you can get an access token, an id token and - optionally, if you request it - a refresh token. The id token is usually not needed for our application. The access token is valid for 45 minutes and is the token to use to authenticate against our API. The request token can be used to get new access tokens and is valid for 2 weeks. You also can use it to get new refresh tokens. This will work up to 90 days. After the last refresh token expires, a new user interaction (login) is required for security reasons.

You can also look at our python example implementation on github .

You can get the OAuth details like token URL and client ID from the config at the python example or from the API description .

To properly implement your own client, you have to implement the scenarios where:

  • An access token expired → Get new token (e.g. via refresh token or redirect user to authentication page)
  • A refresh token expired → Get new token (e.g. via refresh token or redirect user to authentication page)
  • A refresh token family expired → Redirect user to authentication page

Test Authenticating with the help of the swagger interface

1: Go to https://api.bionyx.io/ and press “Authorize”.

2: For your own client: Copy the URLs, the client id and the scope. You can test the flow with swagger by pressing “Authorize” again and logging in with your bionyx user. Continue by executing the API-Calls directly from swagger.

If you did not contact us to get your own OAuth 2.0 client, you are using our public client. In this case you do not need to write anything into the client_secret field. Leave it as it is.

Make sure to select the scope https://ekeybionyxprod.onmicrosoft.com/3rd-party-api/api-access when authenticating in the swagger interface.

This scope is also required when you authenticate from your own client.

If you are implementing your own client: When you use MSAL you can reuse the public OAuth 2.0 client for testing - everything works out of the box. Otherwise, you might need a different redirect uri - which we would have to whitelist. In this case, please contact our product management. We will verify your request and create an own OAuth2.0 client for you.

Configuring functions

After authenticating, you can use our API.
Take a look at the documentation.

Our devices are currently mainly used to provide inputs to other systems.
Therefore, this is the only type of interaction we support.

It is in the nature of this type of interaction that we send you requests - not the other way around.
This is why our API (only) allows you to configure HTTP requests to your API.
It also allows an efficient (polling-free) integration of our devices.
This means that you need an API our devices can send requests to.
To authenticate our devices, you can add some kind of token to the HTTP requests, which we are the only ones to know.
You will find detailed information about this under Security details.

So before you start, first make sure you have an API our device can use to trigger functions.
Then you can implement the process below.
Our python example implementation on github could help you with that.

First, you have to find out which ekey bionyx system the logged-in user is in.
Make the GET/systems request. You will get the name of the system and a flag indicating the user’s own (main) system. Then, present the systems to the user, so that he can choose the desired system for the function.

Below, you can find a diagramm showing the relations between users, systems, ekey devices and the function-webhooks you create.

Secondly, present all functions you could export to ekey bionyx to the user.
He has to select the ones that should actually be exported to the selected ekey bionyx system.
Note that while most users have one single system, some might have two or more (e.g. home system and office system).
It would be nice however, to be able to auto-select one’s own or single system by default.

Be aware that all functions must have a function name and a location name.
These will affect how the functions are shown to the user in the ekey bionyx app.
You also have to give your integration a static integration name (e.g. your product name).
This allows the ekey bionyx app to show all functions sorted by the integration they belong to (e.g. functions of product A, functions of product B, etc.).

Once the user has selected all relevant functions, you can export them one by one to ekey bionyx via a request to POST/systems/{systemId}/function-webhooks. In this request you have to add all relevant information (see api.bionyx.io ) for the HTTP request to your API.

The API allows you to fully define a custom HTTP request our device will send. This means you can define a custom URL, body, headers and more. We will however prevent the usage of some headers (as documented at api.bionyx.io ) for security reasons. The system will ignore these headers if they are set.

Counting from now, ekey bionyx knows how to send requests to your API!
The user can trigger your functions from the ekey bionyx devices and from the ekey bionyx app.
Continue with assigning new functions to fingers.

Configuring explicitly a device which executes the function webhook (optional)

You could also explicitly configure a device which executes the request every time it is triggered by the app in the “Smart home connections” menu.
It is also possible to change the HTTP request icon or name there.