- General
- Authorization
- Programs and Options
- States
- Settings
- Power State
- Setpoint Temperature Refrigerator
- Setpoint Temperature Freezer
- Setpoint Temperature Bottle Cooler
- Setpoint Temperature Chiller
- Setpoint Temperature Wine Comp.
- Super Mode Refrigerator
- Super Mode Freezer
- Eco Mode
- Sabbath Mode
- Vacation Mode
- Fresh Mode
- Current Map
- Names of Maps
- Functional Light
- Functional Light Brightness
- Ambient Light
- Ambient Light Brightness
- Ambient Light Color
- Ambient Light Custom Color
- Events
- Commands
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"
}