Introduction

A device is not only identified by an identifier and secret, but also needs a unique identifier, called uuid. This uuid is in a */key/value/key2/value2* format, for example:

vendor: mycompany
serial: 1234
uuid: /vendor/mycompany/serial/1234

Start Login

Authenticating a device happens in two steps. First, your device obtains a code from our servers:

Request

POST /oauth/token HTTP/1.1
Host: connect-testing.secupay-ag.de
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=device&client_id=abcd1234&client_secret=bcde2345&uuid=cdef3456

Response

{
    "device_code": "defg4567",
    "user_code": "efgh5678",
    "verification_url": "https://www.example.com",
    "expires_in": 1200,
    "interval": 5
}

This tells you that you can verify your authentication at https://www.example.com, using the user code efgh5678.

Errors

400 Bad Request

Error "invalid_client"
{
    "error": "invalid_client",
    "error_description": "The client credentials are invalid"
}
{
    "error": "invalid_client",
    "error_description": "Client credentials were not found in the headers or body"
}
Error "unsupported_grant_type"
{
    "error": "unsupported_grant_type",
    "error_description": "Grant type \"foo\" not supported"
}
Error "invalid_request"
{
    "error": "invalid_request",
    "error_description": "The grant type was not specified in the request"
}
{
    "error": "invalid_request",
    "error_description": "Missing parameters: \"uuid\" or \"code\" required"
}

401 Unauthorized

{
    "error": "invalid_device",
    "error_description": "device with given uuid not configured"
}

Approve User-Code

Now, you open a browser, log in to the verification URL and enter this user code for the device you are trying to authenticate within the next expires_in seconds.

Get Token

Meanwhile the user is redirect to the verification URL, the device can poll our authentication service every interval seconds, to see if the user code has been entered correctly, and thus a token can be obtained.

Request

POST /oauth/token HTTP/1.1
Host: connect-testing.secupay-ag.de
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=device&client_id=abcd1234&client_secret=bcde2345&code=defg4567

Response

{
    "access_token": "fghi5678",
    "expires_in": 1200,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "ghij6789"
}

When succesful, you will receive a refresh token, which you will use from this moment on, until you refresh it again.

Errors

400 Bad Request

{
    "error": "invalid_code",
    "error_description": "parameter code is not valid"
}

401 Unauthorized

{
    "error": "authorization_pending",
    "error_description": "waiting for user to enter correct user_code"
}