Coordinate the Client Credentials and Device IDs

New devices need to be registered in our system. For productive use, a new device class may require a new UUID naming schema with its own parameters. If necessary, we will create one for you.

Please register your devices together with our help desk. You will receive:

• one client ID and client secret for OAuth authentication;
• one device UUID per device.

Client ID and client secret are also commonly referred to as client credentials.

Internet shops are treated as one virtual device. You will receive one device UUID per shop domain.

Request the Device Registration

Before the device can be used, it needs to be registered in our system.

The device registration happens in a two-step process. At first, the device needs to call the authentication service to receive a device code and a user code. Then the registration is confirmed, entering the user code by hand.

The endpoint to request the registration is POST /oauth/token. You need to pass the client credentials and the device UUID.

If everything is fine, the API responds with 200 OK and some details:

The device needs to memorize the device_code in a safe place. It is used in subsequent calls.

The user_code is to be displayed, so that you can confirm the registration. You can do this in self-service in SecuOffice, or make our help desk do this for you.

Confirm the Registration in SecuOffice

You can confirm the device registration in self-service, if you have the needed permissions.

After you have logged in to SecuOffice, you need to perform the following steps:

1. Open Smart Devices » Devices, and look up your device.
2. Click the action button with the handshake symbol. The terminal autentication form opens.
3. Enter the user_code in the field labelled "PIN", and confirm execution.

A small layer will confirm success or failure within the next seconds.

Confirm the Registration Via Hotline

If you want or need our phone service to do this for you, please call +49(0)35955/7550825.

Please have the device UUID ready, and the user code you have received from the API. Our hotline personnel will ask you for it.

Start a Device Session

Once the device is registered, you can authenticate using OAuth. This means you request a session token, and use it for authentication in the subsequent calls.

The endpoint to request the OAuth token is POST /oauth/token. You need to pass the vendor client credentials, and the device code (as code). The grant type is still device.

If evreything is fine, the API responds with 200 OK, and the token amongst other things:

The OAuth access token is found in access_token (line 6). It is valid for 1200 seconds (s. expires_in at line 7). The access token is to be sent in all subequent calls.

Your system should also memorize the refresh_token. It can be used to create a new token without sending the device code again, as long as the session is valid.

Renew the Device Session

Once you have received a device token, you can renew the session using the refresh_token. You have received it with the original token.

The endpoint to request the OAuth token is POST /oauth/token. You need to pass the vendor client credentials, and the refresh token, but not the device code. The grant type is refresh_token.

If the everything is fine, the API responds with 200 OK, and some data:

You will receive the OAuth access token (line 6) as before. There is no refresh token, since it stays unchanged for the current session.