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)

Authorization Server

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

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:

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

Expand source

?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}&state={state}

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

Expand source

?code={code}&grant_type=authorization_code

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

Expand source

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

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

Expand source

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

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

Expand source

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

Response Header

• Content-Type: application/json

Response Parameters

Example

Expand source

{
    "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

Example

Expand source

grant_type=device_code&device_code={device_code}&client_id={client_id}

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

Expand source

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

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

Expand source

grant_type=refresh_token&refresh_token={refresh_token}&client_secret={client_secret}

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

Expand source

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

In the following, the possible authorization errors are explained.

(Device) Authorization Endpoint

HTTP Status Codes

Error Cases

Redirection Example

Expand source

<redirect_uri>?error=access_denied&error_description=login+aborted+by+the+user

JSON Example

Expand source

{
    "error": "unauthorized_client",
    "error_description": "request rejected by client authorization authority (developer portal)"
}

Access Token Endpoint

HTTP Status Codes

Error Cases

Example

Expand source

{
    "error": "invalid_grant",
    "error_description": "invalid refresh_token"
}