Access_tokens (v2 client)

Authentication & Authorization with v2 client

There is a way to save & restore access_tokens and refresh_tokens without re-authenticating. This may be useful to decrease/eliminate HTTP_429_TOO_MANY_REQUESTS (API rate limit exceeded) errors.

Note that the v1 client uses a SessionId rather than access tokens.

Example

from evohomeclient2 import EvohomeClient

c = EvohomeClient(username, password)

# Save these...
refresh_token = c.refresh_token 
access_token = c.access_token
access_token_expires = c.access_token_expires

c = None

# ...and restore later
d = EvohomeClient(username, password, refresh_token=refresh_token,
                  access_token=access_token, access_token_expires=access_token_expires)

Further detail

For the v2 client, the following is worth understanding.

Authorization (access_token)

Whenever a call is made to Honeywell's servers (i.e. by using any EvohomeClient2 method), the access_token (authorization token), if provided, will be used rather than generating a new one. This can happen without validating the user's credentials.

A new access_token will automatically be requested whenever it has expired, or it is found to be invalid/unauthorised. For this to happen, there needs to be a valid set of credentials identifying the user's account...

The code can handle an expired/null token, but not all (contrived) 'invalid' tokens (e.g. the the token == "hello", and it expires a month into the future) - such tokens may result in unpredictable behaviour.

Authentication (refresh_token)

Whenever a new access_token is needed (i.e. re-authentication), if a refresh_token is provided, it will be used in preference to any user credentials (I believe this doesn't count against an API limit). If that fails for any reason, the user credentials (username, password) will be used instead (this counts).

Theory says (I haven't tested it) that you can supply a refresh_token, and no credentials, and that would be OK (until, for some reason, the refresh_token becomes invalid).

d = EvohomeClient(username, "bad-password", refresh_token=refresh_token,
                  access_token=access_token, access_token_expires=access_token_expires)

Multiple Sessions per User account

It is possible to have multiple instances of the EvohomeClient2, and special consideration needs to be taken if they are using the same user account (i.e. the same username/password).

Notably, the refresh_token is refreshed every time a new access_token is created. Thus, the two instances of the client cannot easily 'share' a refresh_token; when it is used by one, the other will instantly have an out-of-date token.

You could pass tokens (any of the above tokens) from one to the other, but there is no supported method for this in the client. It may be easier to create an instance of the client only once, and pass the reference of that around your consuming apps as required.