Here’s how to have your application login to homey with just your e-mail address and password (once) and obtain a refresh token for subsequent access.
Notice, the refresh token will expire, either by expiration or revocation.
There are quite a few more things to discover, but this will get you going.
In the following steps, I didn’t register a new application (probably possible, but I didn’t look into that yet), I just borrowed the client_id and client_secret from developer.athom.com (client_id=598d85a330e1bb0c0d75b8eb and client_secret=ba93fc861b204732607169fb29c2708f1da7e17f). Other combinations for client_id and client_secret will also work (for example homey.ink), as long as the redirect_uri matches.
Step 1, get a JWT with your credentials.
HTTPS-POST your e-mail address and password, form-url-encoded, to accounts.athom.com/login.
No client_* needed at this time.
The JSON reply is the JWT as {“token”: “jwt”}
Step 2, obtain a delegation code.
HTTPS-GET accounts.athom.com//authorise?client_id=xxx&redirect_uri=uri&response_type=code&user_token=JWT from previous step
Since I used the client_id from developer.athom.com, the uri in this case is the aforementioned. The redirect_uri is important and will be checked (as it should be)
Be aware, the HTTP result will be a 302 (redirect).
The location-header contains a query parameter ‘code’. It’s value is the delegation code. The header looks like: “location: https://redirect_uri?code=89bc40ceXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX29”.
Step 3, get an access token
HTTPS-POST api.athom.com/oauth2/token, form-url-encoded
Body: client_id=XXX&client_secret=YYY&grant_type=authorization_code&code=Delegation code from previous step
The JSON result looks like this in readable format:
{
“access_token”: “51163d8xxxxxxxxxxxxxxxx8282579f8fe77ee”,
“expires_in”: 3660,
“refresh_token”: “f7d635axxxxxxxxxxxxxxxx1c2a258f4e33d15b”,
“token_type”: “bearer”
}
Use the access_token for the next step, but also keep the refresh_token. You will need the refresh_token in the future to obtain a new bearer code.
Step 4, obtain a JWT to login to your homey
HTTPS-POST api.athom.com//delegation/token?audience=homey
Add an http-header: Authorization: Bearer access_token from previous step or step 6
The JSON result contains just the JWT.
Step 5, login to homey
HTTPS-POST uri/api/manager/users/login
Body: {"token”:”JWT from step 4”}
The reply is the desperately sought bearer token in JSON format.
uri can be a number of things:
- The fastest option is homey’s local IP address.
- The second is a local qualified DNS name.
- Another option is: w-x-y-z.homey.homeylocal.com (w-z = the local IP address bytes).
- More options exist, all through the cloud and pretty much equally slow.
The bearer code will expire after 24 hours. To obtain a new one without user credentials, see step 6.
Step 6, refresh the bearer token
The bearer token expires every 24 hours and with good reason.
If you saved the refresh_token from step 3, you can obtain a new access_token and hence a new bearer token. Note: this will not go on indefinitely. At some point you will have to login again.
HTTPS-POST api.athom.com/delegation/token?audience=homey, form-url-encoded.
Body: client_id=XXX&client_secret=YYY&grant_type=refresh_token&refresh_token=<refresh_token>
The response is similar to the response in step 3. Use the access_token to repeat steps 4 and 5. Keep the refresh_token for the next refresh (The refresh_token may change).
With the access_token received in step 3 or 6 you can find useful information like cloud id and homey’s ip address:
HTTPS_GET api.athom.com/user/me
Add header: Authorization: Bearer <access_token from step 3 or 6>
