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

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