API usage questions

[JueBag]

With the help of @MichaelHanna I was able to get my first API token. Thanks for that!

Now I do have some follow up questions:

Refresh Token:

I noticed that the Refresh Token stays the same. Is that true for all the time?

Regarding the documentation for refreshing a token I do suggest to use the scope 

IoT%20User%20offline_access

in Step 1 as well, that way the step of refreshing the API Token is done more easily.

Usage of API calls:

In the Section IOT you show examples on how to get InstallationID etc.

Those examples are using https://api.viessmann.com/iot/v1 will that remain possible after July 15th? I guess not, otherwise, we would not need an AccessToken.

Only in the section Service documents a Version 3 is stated. Doing a request on those just returns.

{

    "startedAt": "2021-06-18T12:24:21.567Z",

    "version": "3.4.0"

}

How should one get a document with that?

[MichaelHanna · Accepted solution]

Hi @JueBag ,

Thanks for your suggestion concerning the documentation. We will check how we can have clearer overview for the user, which scopes are available beforehand.

Once you requested a refresh token, it will stay the same so that you can use it to obtain an access token. However, when requesting another refresh token, it will be new one that you will get. My suggestion is creating a refresh token once and then only performing step 2 in the authorization flow: https://developer.viessmann.com/en/doc/authentication

Please do not get confused with the versioning within the API calls (URLs). There is no new API that is released after July 15th. What we are doing is that we are disabling an API key that is currently being by a lot of users. Instead, our intention is that everyone is obtaining their own personal API key through the Developer Portal.

The versioning you are seeing is related to the services behind the API call and can be different for each service. You find the version of a service at the top of each page in the documentation, see the attachment image for installation features.

I hope this answers your questions.

Best,

Michael

[JueBag]

Thanks for the answer, I have to admit to been fooled by the Chrome browser. Chrome gave me a response by pasting the string like "https://api.viessmann.com/service-documents/v3/" into the address line. It WAS my understanding that doing it that way no Authentification would have been used. This is not case, although I have no idea (stupid .me) how my token could have been used by the browser. I did use the token on a POSTMAN tab.

[MichaelHanna]

Hi @JueBag,

your token has not been used by the browser I assume. Calling https://api.viessmann.com/service-documents/v3/ does not need any token in order to call the service. This is why your browser received the correct response.

If you for example call https://api.viessmann.com/iot/v1/equipment/installations/ within your browser, you will get an error 401 "UNAUTHORIZED"; "NO TOKEN AVAILABLE", because you need an access token to call this service.

Hope this helps.

Best,

Michael