Device Flow

As the device flow is still in beta, we appreciate your feedback if you notice any bugs or issues.

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

  • client_id [mandatory]: generated client ID (see Applications)
  • scope [optional]: space separated list (escaped by %20) 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

  • device_code [mandatory]: device verification code
  • user_code [mandatory]: end-user verification code
  • verification_uri [mandatory]: 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

  • grant_type [mandatory]: 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 [mandatory]: device verification code, which was returned by device authorization call
  • client_id [mandatory]: generated client ID (see Applications)
  • client_secret [optional]: secret of the client that requested the code

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

  • id_token [mandatory]: same as access token
  • access_token [mandatory]: token to be used in subsequent Home Connect API requests
  • expires_in[mandatory]: expiration time of the access token and id_token in seconds, default: 86400
  • scope[mandatory]: permissions requested by the client application separated by space
  • refresh_token [mandatory]: refresh token (expires if it wasn't used within 2 months)
  • token_type [mandatory]: 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"
}