Device Flow

The Home Connect API supports the OAuth2 Device Flow as shown in the figure below:

DeviceAuthenticationFlow.png

 

Before you can start with the authorization of your application, you need to register your application in the developer portal first. After registration, you get a client ID. You should generate one client ID per client.

 

Device Authorization Endpoint

Device Authorization Request

HTTP Method

POST

URL

https://api.home-connect.com/security/oauth/device_authorization

Request Header

  • Content-Type: application/x-www-form-urlencoded

Body Parameters

Key Value Description
client_id

Required.

Client identifier which is generated after application registration.

scope

Optional but recommended.

Space separated (escaped by %20) list of permissions. Possible permissions are IdentifyAppliance (always required), Monitor, Control (see Authorization Scopes).

Example

client_id={client_id}&scope={scope}

 

Device Authorization Response

The request will return the device code and user code in the HTTP body.

HTTP Status Code

Code Short Description Long Description
200 OK Request succeeded
400 Bad Request see Authorization Errors
415 Unsupported Media Type The request's Content-Type is not supported, expected: application/x-www-form-urlencoded
503 Service Unavailable see Authorization Errors

Response Header

  • Content-Type: application/json

Response Parameters

Key Value Description
device_code

Required.

Device verification code.

user_code

Required.

End-user verification code.

verification_uri

Required.

End-user verification URI on the authorization server. The URI should be short and easy to remember as end-users will be asked to manually type it into their user-agent / webbrowser.

verification_uri_complete

Optional.

Verification URI that includes the user_code (or other information with the same function as the user_code), designed for non-textual transmission.

expires_in

Optional.

Lifetime in seconds of the device_code and user_code, default: 300.

interval

Optional.

Minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint, default: 5.

Example


{
    "device_code": "{device_code}",
    "user_code": "{user_code}",
    "verification_uri": "{verification_uri}",
    "verification_uri_complete": "{verification_uri}?user_code={device_code}",
    "expires_in" : 300,
    "interval": 5
}

 

User Interaction

see Section 3.3 of Device Flow

 

Access Token Endpoint

Device Access Token Request

After displaying instructions to the user, the client can start querying an access token by using this endpoint. In addition to the error codes defined in Section 5.2 of [RFC6749], the following error codes are specified by the device flow for use in token endpoint responses:

  • authorization_pending: authorization request is still pending as the end-user hasn't yet completed the user interaction steps. The client SHOULD repeat the Access Token Request to the token endpoint.
  • access_denied: end-user denied the authorization request. The client SHOULD stop sending requests to this endpoint.
  • slow_down: client is polling too quickly and SHOULD back off at a reasonable rate (see returned interval).
  • expired_token: device_code has expired. The client SHOULD stop sending requests to this endpoint, it will need to make a new Device Authorization Request.

HTTP Method

POST

URL

https://api.home-connect.com/security/oauth/token

Request Header

  • Content-Type: application/x-www-form-urlencoded

Body Parameters

Key Value Description
grant_type

Required.

Set this parameter to urn:ietf:params:oauth:grant-type:device_code or device_code if the access token is to be requested with the device code by a preceding authorization request.

device_code

Required.

Device verification code which was returned by device authorization call.

client_id

Required.

Client identifier which is generated after application registration.

client_secret

Optional.

Secret of the client that requested the code. It is generated after application registration.

Example

client_id={client_id}&grant_type=authorization_code&code={code}

 

Device Access Token Response

The request will return the access token and a refresh token in the HTTP body.

HTTP Status Code

Code Short Description Long Description
200 OK Request succeeded
400 Bad Request see Authorization Errors
403 Forbidden see Authorization Errors
415 Unsupported Media Type The request's Content-Type is not supported, expected: application/x-www-form-urlencoded
503 Service Unavailable see Authorization Errors

Response Header

  • Content-Type: application/json

Response Parameters

Key Value Description
id_token

Required.

Same as access token.

access_token

Required.

Token to be used in subsequent Home Connect API requests.

expires_in

Required.

Expiration time of the access token and id_token in seconds, default: 86400.

scope

Required.

Permissions requested by the client application separated by space.

refresh_token

Required.

Token to be used to refresh access token (expires if it wasn't used within 60 days).

token_type

Optional.

Type of the token, currently always Bearer.

Example


{
    "id_token": "{id_token}",
    "access_token": "{access_token}",
    "expires_in": 86400
    "scope": "{scope}",
    "refresh_token": "{refresh_token}",
    "token_type": "Bearer"
}