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
| Key | Value Description |
|---|---|
| client_id |
Required. Client identifier which is generated after application registration. |
| redirect_uri |
Optional. Redirect URI which is defined in registered application. If this parameter isn't used then the first defined redirect URI is used. |
| response_type |
Required. Value must be code. |
| scope |
Optional but recommended. Space separated (escaped by %20) list of permissions. Possible permissions are IdentifyAppliance (always required), Monitor, Control (see Authorization Scopes). |
| state |
Optional but recommended. This 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. |
| nonce |
Optional. Random string that will be returned in the JWT token. It is used to mitigate replay attacks. (max 50 characters) |
| code_challenge |
Optional. The code challenge is created by the client which is derived from the code verifier by using one of the following transformations:
|
| code_challenge_method |
Optional. Method which was used to create the code challenge from the code verifier.
|
Example
?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
| Code | Short Description | Long Description |
|---|---|---|
| 302 | Found | Redirection in case of success or Authorization Error |
| 400 | Bad Request | see Authorization Errors |
| 503 | Service Unavailable | see Authorization Errors |
Response Header
- Content-Type: text/html
Query Parameters
| Key | Value Description |
|---|---|
| code |
Required. 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
?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
| Key | Value Description |
|---|---|
| grant_type |
Required. Value must be authorization_code. |
| code |
Required. The code retrieved from the preceding authorization request. |
| 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. Please note that this parameter is required for this flow. |
| redirect_uri |
Optional. Redirect URI which is defined in registered application. If this parameter isn't used then the first defined redirect URI is used. Please note that it is required if the redirect_uri parameter was included in the authorization request. |
| code_verifier |
Required. Code verifier which was used during code challenge creation on client side. Please note that it is required if the code_challenge parameter was included in the authorization request. |
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
| 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. Max length: 4096, normally: ~ 1000 characters depending on the used scope |
| 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). Max length: 256, normally: ~ 100 characters |
| 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"
}