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

• client_id [mandatory]: generated client ID (see Applications)
• redirect_uri [optional]: registered callback URL in developer portal (see Applications)
• response_type [mandatory]: must be code
• scope [optional]: space separated (escaped by %20) list of permissions. Possible permissions are IdentifyAppliance (always required), Monitor, Control (see Authorization Scopes).
• state [optional]: this recommended parameter shall be used to prevent cross-site request forgery. Use random number or hash of the session cookie and verify in the final redirect that the included value is the same as the initial value.

Example

<authorize_uri>?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

• code [mandatory]: code to be used in a subsequent access token request(see also Section 4.1.2 of [RFC6749]). It expires after 10 minutes.
• grant_type [optional]: type of the returned code, currently always authorization_code
• state [optional]: state provided by the client in the authorization request

Exemplary Redirection

<redirect_uri>?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

• client_id [mandatory]: generated client ID
• client_secret [optional]: generated client secret (see Applications) Please note that this parameter is required for this flow.
• redirect_uri [optional]: registered callback URL in developer portal
• grant_type [mandatory]: must be authorization_code
• code [mandatory]: code, which was returned by authorization call
• state [optional]: can be used to store client state information

Example

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

• 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
• state [optional]: state provided by the client in the request

Example

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