The Authorization API uses an OAuth 2.0 Authorization framework for authorizing the access to the different API interfaces. The API supports three different authorization flows:

• Authorization Code Grant
• Resource Owner Grant - only available upon special request
• Implicit Grant - only available upon special request

For more details regarding the OAuth 2.0 authorization flows, please visit the RFC 6749 .

As prerequisite a new client must be registered with the LIVISI home backend, in order to receive its unique client credentials, i.e. id and secret. Providing the client credentials and credentials of a registered SmartHome user, the client can request a refresh and an access token.

Authorization Code Grant

For obtaining access tokens the client application must use the OAuth authorization code flow as describe in section 4.1 of RFC 6749. The client application should point the user agent to the login page, by issuing a GET request with the following request parameters:

• response_type must be set to code
• client_id must be set to the specific client application identifier
• redirect_uri is the URI to which the user agent should be redirected once an authorization code has been issued. This URI should be part of the client application and must be registered with LIVISI beforehand

Optional parameters:

• lang defines the language in which the login page shall be displayed. Supports de-DE, en-GB, fr-FR and nl-NL. Defaults to de-DE.
• state a piece of information that acts like a cookie, allowing the client to maintain state during the authentication process
• scope defines the target device that the user needs to access

Example:

https://auth.services-smarthome.de/AUTH/authorize?response_type=code&client_id=<cliendID>&redirect_uri=<URIEncodedRedirectURI>

As a result of the GET request described above, the user agent receives a login page where the user must enter their credentials and submit them. This page is provided by the authorization server. The authorization server validates the request, and if they are accepted it redirects the user agent via a GET request to the provided redirect_uri, along with these request parameters:

• code which contains the authorization code
• state which matches the state information included in the initial request (optional)

Example:

<RedirectURI>?code=b1276486a23e45e3a280fd527f9e3f4d

Once the control is returned to the client application via the second GET request, it can use the new authorization code to request an access token. It does that by issuing a POST request to the authorization server. Example:

curl --location --request POST 'https://auth.services-smarthome.de/auth/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <base64 encoded clientId:clientSecret>' \
--data-raw '{
  "Grant_Type":"authorization_code",
  "Code":"<the authorization code",
  "Redirect_Uri":"<the same redirect URI as in the initial request>"
}'

The request must be authenticated using HTTP Basic authentication with the respective client application identifier and secret. This is achieved by adding the Authorization header in the request, using the Basic schema and the base64 encoded clientId:clientSecret.

The Content-Type header of the request must be set to application/json.

As a result of this POST request, the client application receives a response containing an access token and a refresh token. e.g.:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IndLdDA4OVc4MGNUSnVmRTVFNTU3N2c4ZjE5RSJ9.eyJjbGllbnRfaWQiOiIzNTkwMzUwMCIsInN1YiI6ImFkaTAyNyIsImRldmljZSI6IjkxNDEwMDAwNTAyNyIsImNsaWVudF9wZXJtaXNzaW9ucyI6IjAiLCJ0ZW5hbnQiOiJSV0UiLCJ1c2VyX3Blcm1pc3Npb25zIjoiRkZGRkZGRkZGRkZGRkZGRiIsInNlc3Npb24iOiI1OTMwZmQyYTY5NWU0NTAyYWU4YjIwZDQzY2VmNDMzYSIsImlzcyI6IlNtYXJ0SG9tZUFQSSIsImF1ZCI6ImFsbCIsImV4cCI6MTQ4NjgyNjU1MCwibmJmIjoxNDg2NjUzNzUwfQ.OaxnrkkCMtky7VfjyIYcLxkzD78O5eSTpRYb0SsO28zGx4esPUzn-pjg8Ci9rxLuZBU7OCJ-sxCcKwW7cQNmxK9C6fKuslFtvUKRoQNeVySSiH1oGlelIPHiEUEMKvaVETUFwm8H_XHnrlQEB8DLlLjXif9Xq6s2dDYLaPRsrIOT9JL2LbdGHPnzPd40RfgS23GkFBCYBX7zliqHt-TY92spvqLPcsxVWiR46iFCYBOuUqrW0bHS-waXO-ZCvsNnnTLj6DnC5Ej6NOKdwkyVYupf5pUUhf13fhHAlO9t7KVUqzsumB_tBRXGjY9CJP4kmvrCU_DAjLGShWXb-MT68Q",
    "token_type": "Bearer",
    "expires_in": 172800,
    "refresh_token": "5d2c6266741e446abaee9644bd647558"
}

Detailed description of the interfaces required for this flow can be found in the OpenAPI reference The following diagram describes the flow mentioned above:

Once the access token is obtained, any request to the API will have to include the Authorization header with the Bearer scheme and the token value:

Authorization:  Bearer <accessToken>

Refreshing an access token

Precondition: An access token has been issued before, and it includes a refresh token.

Once an access token expires, the client gets back a 401 (Unauthorized) error on all requests that require authentication, with a specific error code: 2007.

To renew the access token, the client application must issue a POST request with the following body:

curl --location --request POST 'https://auth.services-smarthome.de/auth/token' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <base64 encoded clientId:clientSecret>' \
--data-raw '{
	"refresh_Token":"450f14145b5a49a48b8b44saf0fbbe11",
	"grant_Type":"refresh_token"
}'

The request must be authenticated using HTTP basic authentication, using the client application identifier and secret. This is achieved by adding the Authorization header in the request, using the Basic schema and the base64 encoded clientId:clientSecret.

The Content-Type header of the request must be set to application/json.

As a result of this POST request, the client application receives a response containing an access token and a refresh token as seen in the response above.

The client application may also choose not to use the refresh token but request a new token, but in this case the session context is lost, and it will be required to initiate a new connection to the user’s device.