Getting Started

Introduction


Welcome to the Viessmann API Getting Started guide. With just a few short steps this tutorial will familiarize you with the basics and establish a foundation for accessing Viessmann APIs. Whether you are an independent developer or work for a big company, we will provide you with the right tools for the job.

Prerequisites


Each endpoint of the Viessmann API requires authentication with an access token. Such a token can be obtained by following the OAuth 2.0 process, so you first have to register a new OAuth 2.0 client specifying your desired Client Name and a list of Redirect URIs.

If you are not familiar with OAuth, register the client with any valid URI as Redirect URI. This guide does not require any knowledge of OAuth. It becomes relevant in case you want to build an application that accesses user-centric features of our API. This however would exceed the scope of this tutorial.

For security reasons, we use the authorization code with PKCE flow (Proof Key for Code Exchange). Additionally, the authentication form of our IAM platform is protected against abusive activities via Google reCAPTCHA.

Throughout this tutorial, we present all HTTP requests as cURL commands, even though some requests can only be performed via browser due to our captcha validation.

Please refer to the section Authentication for more information on authorization.

Get access token


Now that you have your client registered, we can start the process of obtaining an access token. We will use the following example client data:

username: User123
password: Secret123
redirect uri(s): "http://my-website.com/oauth-callback"
client id: my_oauth_client_id

To obtain our token, we need to perform two requests on our IAM platform with several parameters:

  • client_id
  • redirect_uri
  • response_type (= code)
  • code_challenge / code_verifier
  • scope (= Iot User)

The first request has to be done via browser, as the endpoint that is called is protected with a captcha. So instead of submitting a cURL command in your terminal (or using http tools like postman) you need to open up a browser with the following URL and then login with your credentials (In a real-world scenario, your application would redirect the user to this URL):

HTTP
https://iam.viessmann.com/idp/v2/authorize?client_id=my_oauth_client_id&redirect_uri=http://my-website.com/oauth-callback&response_type=code&code_challenge=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c&scope=IoT%20User

For completeness, also represented as cURL command:

curl command
curl -X POST "https://iam.viessmann.com/idp/v2/authorize?
client_id=my_oauth_client_id
&redirect_uri=http://my-website.com/oauth-callback
&response_type=code
&code_challenge=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c
&scope=IoT%20User"

Make sure to replace the values highlighted in red with your oAuth client data. The code_challenge / code_verifier is, simply spoken, a random string that must be the same in both requests. It is covered in more detail in our authentication section. In this tutorial you can just use the value provided above.

The HTTP response you get will have status code 302 and contain a redirect to your callback URI with the authorization code (your browser will most likely redirect you immediately):

HTTP
HTTP/1.1 302 FOUND
Location: http://my-website.com/oauth-callback/?code=m0wqM4ksQ7w3OnarOqjW2iDrO7e7Capn5dSlQL6aUZ4
Content-Type: text/html

<HTML>
<TITLE>302 Found</TITLE>
<H1>Found</H1>
The document has moved
<A HREF="http://my-website.com/oauth-callback/?code=m0wqM4ksQ7w3OnarOqjW2iDrO7e7Capn5dSlQL6aUZ4"
>here</A>.
</BODY></HTML>

In the second request, we will use this code to retrieve our access token:

curl command
curl -X POST "https://iam.viessmann.com/idp/v2/token" 
--header "Content-Type: application/x-www-form-urlencoded" 
--data-urlencode "grant_type=authorization_code" 
--data-urlencode "code_verifier=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c" 
--data-urlencode "client_id=my_oauth_client_id" 
--data-urlencode "redirect_uri=http://my-website.com/oauth-callback" 
--data-urlencode "code=m0wqM4ksQ7w3OnarOqjW2iDrO7e7Capn5dSlQL6aUZ4"

The HTTP response you get will have status code 200 OK and contain the access token in JSON format:

HTTP
HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU...",
    "token_type": "Bearer",
    "expires_in": 3600
}

Now you obtained your token that can be used for queries to our API.

Query the API


Now that you have obtained an access token, it is time to make a sample call to our platform API. As stated earlier above, when making an API call with your access token you always need to send the access token in the HTTP Authorization header bearer token.

Let's query the user service of our platform API to get information about our user account:

curl command
curl -X GET "https://api.viessmann.com/users/v1/users/me?sections=identity" 
-H "Authorization: Bearer eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU..."

Et voilĂ ! The result you get will look similar to this:

HTTP
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

{
    "properties": {
        "loginId": "your-login-id@yourcompany.com",
        "address": {
            "postalCode": "12345",
            "city": "some city",
            "street": "Teststreet",
            "houseNumber": "42",
            "countryCode": "de"
        },
        "clientExtId": "100",
        "languageCode": "de",
        "userState": "ACTIVE",
        "name": {
            "firstName": "your first name",
            "familyName": "your last name"
        },
        "validity": {
            "from": "2018-06-11T07:14:47+0200"
        },
        "contacts": {
            "telephone": "+49 1234 5678",
            "telefax": "+48100234234",
            "email": "user@viessmann.com"
        },
        ...
    },
    ...
}

This approach can be applied to all endpoints described in our API documentation, so do not hesitate and just try it out directly!