API Authorization

Bosch smart home currently supports working with confidential OAuth2 clients [OAuth2 RFC6749 - Section 2.1] only. In order to interact with the digital twins of bosch smart home devices and services, a client must interact with the Bosch smart home authorization server in form of following HTTP requests.

Discovery Request

curl --request GET 'https://smarthome.authz.bosch.com/auth/realms/home_auth_provider/.well-known/openid-configuration'

The response of this request is a JSON structure containing the OAuth2 discovery information.

Authorization Request

curl --request GET '<authorization_endpoint>?response_type=code&scope=<scope_list>&client_id=<client_id>&redirect_uri=<redirect_uri>'

Parameter	Value
<authorization_endpoint>	The authoritation endpoint URL obtained in the response of the OAuth2 discovery request
<client_id>	The client ID of your OAuth2 client.
<scope_list>	Space separated list of OAuth2 scopes assigned to your client.
<redirect_uri>	Redirect URI for your receiving the authCode. This must match the configured URI at the auth provider.

The authorize request is typical performed in a browser. The server responds by displaying a UI for the user to provide their bosch credentials. Once the user has successfully logged in, they are psented a consent screen by the server where they must consent to the client accessing their information.

Upon successful authorization the browser is redirect to the configured redirect_uri with the authorization code as query parameter. Upon unsuccessful authorization, e.g. if the user rejected to consent to the data access, the browser is redirect to the configured redirect_uri with the error as query parameter. The list of authorization errors could be found here.

Token Request

curl --request POST '<token_endpoint>' \
          --header 'Accept: application/json' \
          --header 'Content-Type: application/x-www-form-urlencoded' \
          --data-urlencode 'code=<auth_code>' \
          --data-urlencode 'client_id=<client_id> ' \
          --data-urlencode 'scope=<scope_list>' \
          --data-urlencode 'redirect_uri=<redirect_uri>' \
          --data-urlencode 'grant_type=authorization_code' \
          --data-urlencode 'client_secret=<client_secret>'

Parameter	Value
<token_endpoint>	The token endpoint URL obtained in the response of the OAuth2 discovery request.
<auth_code>	The value of the code parameter from the response to the authorization request.
<client_id>	The client ID of your OAuth2 client.
<client_secret>	The client secret of your OAuth2 client.
<scope_list>	Space separated list of OAuth2 scopes assigned to your client.
<redirect_uri>	Redirect URI for your receiving the authCode. This must match the configured URI at the auth provider.

Upon successful token request, a response containing an access token and a refresh token is sent by the server. For example:

{
  "access_token": "****",
  "expires_in": 3600,
  "refresh_expires_in": 0,
  "refresh_token": "****",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "1299ba88-1c61-4c33-aca0-00b05037255a",
  "scope": "****"
}

Upon unsuccessful token request, the server sends HTTP 400 with an error in the response body. The list of token request errors could be found here.

The access tokens issued by Bosch smart home authorization server are valid for 60 minutes. A new access token can be obtained by performing the token refresh request using pviously obtained refresh token. The refresh tokens are valid for a single use within 30 days.

Token Refresh Request

curl --location --request POST '<token_endpoint>' \
          --header 'Accept: application/json' \
          --header 'Content-Type: application/x-www-form-urlencoded' \
          --data-urlencode 'refresh_token=<refresh_token>' \
          --data-urlencode 'client_id=<client_id> ' \
          --data-urlencode 'grant_type=refresh_token' \
          --data-urlencode 'client_secret=<client_secret>'

Parameter	Value
<token_endpoint>	The token endpoint URL obtained in the response of the OAuth2 discovery request.
<client_id>	The client ID of your OAuth2 client.
<client_secret>	The client secret of your OAuth2 client.
<refresh_token>	The refresh token obtained in the response of an OAuth2 token request.

The bevahiour of the token refesh request is the same as the behaviour of the token request discussed above.

Logout Request

curl --request POST '<end_session_endpoint>' \
          --header 'Content-Type: application/x-www-form-urlencoded' \
          --header 'Authorization: Bearer <access_token>' \
          --data-urlencode 'client_id=<client_id>' \
          --data-urlencode 'refresh_token=<refresh_token>' \
          --data-urlencode 'client_secret=<client_secret>'

Parameter	Value
<end_session_endpoint>	The end session endpoint URL obtained in the response of the OAuth2 discovery request.
<client_id>	The client ID of your OAuth2 client.
<client_secret>	The client secret of your OAuth2 client.
<access_token>	The access token obtained in the response of an OAuth2 token request.
<refresh_token>	The refresh token obtained in the response of an OAuth2 token request or token refresh request.

Upon successful execution of logout request, the server send an HTTP 204 response and revokes the provided refresh token.