Authorization Code Grant Flow

The Home Connect API supports the OAuth2 Authorization Code Grant Flow as shown in the figure below:

AuthorizationCodeGrantFlow.png

 

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:

  • plain: code_challenge = code_verifier
  • S256: code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
code_challenge_method

Optional.

Method which was used to create the code challenge from the code verifier.

  • plain (default)
  • S256 (recommended)

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.

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).

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