Home Connect Developer Program

This page does NOT support Internet Explorer. Please use a modern browser like e.g. Google Chrome, Mozilla Firefox or Microsoft Edge.

Authorization

Roles
Copied link to clipboard

The Home Connect API uses the OAuth2 standard as defined in RFC 6749 in order to grant 3rd party access to home appliances which are paired to a Home Connect user account. Every request has to be authorized by an access token as defined in RFC 6750.

User (Resource Owner)

The owner of the home appliance. The home appliance must be paired to the user's Home Connect account.

Resource Server

The Home Connect system which enables the access to the user's home appliances.

Application (Client)

A 3rd party application with the intention to monitor or control user's home appliances.

Authorization Server

The Home Connect authorization server which issues access tokens to the client.

Authorization Scopes
Copied link to clipboard

For all requests on the Home Connect API at least the scope IdentifyAppliance is required.

Furthermore, you can select a set of rows, columns or cells from the following matrix. If you choose a row all cells of this row are included. If you choose, for instance, Dishwasher, then you also get Dishwasher-Monitor, Dishwasher-Control and Dishwasher-Settings. The same inclusion applies to columns.

Note that you should always choose the minimum required set of scopes which is required by your application. This increases the acceptance by your customers.

All available scopes are listed in the following:

Authorization Code Grant Flow
Copied link to clipboard

The Home Connect API supports the OAuth2 Authorization Code Grant Flow as shown in the figure below:

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 application.

Authorization Endpoint

Authorization Request

HTTP Method

GET

URL

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

Query Parameters

Example

Authorization Response

The request will return a HTML login page which has to be presented to the user. When the user presses Login, a HTML grant page is returned. This page informs the user about the requested scope. If the user grants access, an HTTP 302 redirect to the redirect_uri is returned which includes the authorization code as request parameter.

HTTP Status Code

Response Header

  • Content-Type: text/html

Query Parameters

Exemplary Redirection

Access Token Endpoint

Access Token Request

HTTP Method

POST

URL

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

Request Header

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

Body Parameters

Example

Access Token Response

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

HTTP Status Code

Response Header

  • Content-Type: application/json

Response Parameters

Example

Device Flow
Copied link to clipboard

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

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

Example

Device Authorization Response

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

HTTP Status Code

Response Header

  • Content-Type: application/json

Response Parameters

Example

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).
  • expiredtoken: devicecode 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

Example

Device Access Token Response

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

HTTP Status Code

Response Header

  • Content-Type: application/json

Response Parameters

Example

Refreshing an Access Token
Copied link to clipboard

Due to the limited access token lifetime of 86400 seconds (24 hours), the client has to request a new access token as soon as the access token has expired. This can be done by using the following token endpoint.

Access Token Endpoint

Access Token Refresh Request

HTTP Method

POST

URL

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

Request Header

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

Body Parameters

Access Token Refresh Response

The request will return the new access token in the HTTP body.

HTTP Status Code

Response Header

  • Content-Type: application/json

Response Parameters

Example

Authorization Errors
Copied link to clipboard

In the following, the possible authorization errors are explained.

(Device) Authorization Endpoint

HTTP Status Codes

Error Cases

Redirection Example

JSON Example

Access Token Endpoint

HTTP Status Codes

Error Cases

Example