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