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 but required if Proof Key for Code Exchange is enabled in application settings 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 |
Optional but required if Proof Key for Code Exchange is enabled in application settings 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"
}