[Unsupported] Homey v2 REST API

[Magnus_Johansson]

Solved
The error was on my side. I’ve got one Homey but two Homeys registered on my account. When I selected the active one and looked for the bearer I got the correct one.

[Phuturist]

Anyone already figured out of it’s possible to read and/or update variables from the Logic functionality?

[TimTim]

Did you check out https://developer.athom.com/docs/api/HomeyAPI.ManagerLogic.html?

[Phuturist]

@Jamie

Im guesing : http:///api/manager/devices/device/<device_id>/capability/target_temperature

I’m trying to get the measure_temperature value from a sensor. I would figure it would be indeed something like this:

GET: http://<HomeyIP>/api/manager/devices/device/<device_id>/capability/measure_temperature

Unfortunately this does not work, anyone any idea how to do this?

[EDIT]
It looks like there is no getCapabilityValue method under the device class. You will need to get it from the result of the device itself which holds a capabilities object.

[Robin_van_Kekem]

Anyone an idea as to why there isn’t any official REST API?
There used to be one on V1 so I don’t understand why there isn’t any on V2…

[Marlon]

You could parse the output of the api call https://<HomeyIP>/api/manager/devices/device/<device_id> for “capabilitiesObj/measure_temperature/value”

I don’t know if you already looked into it?

    "capabilitiesObj": {
      "measure_temperature": {
        "value": 17.1,
        "lastUpdated": "2019-02-16T14:06:48.855Z",
        "type": "number",
        "getable": true,
        "setable": false,
        "title": "Temperature",
        "desc": null,
        "units": "°C",
        "decimals": 2,
        "chartType": "spline",
        "id": "measure_temperature",
        "options": {}
      }

[Phuturist]

@Marlon

I don’t know if you already looked into it?

Yes, but thanx anyway.

[Marlon]

I have two entries for the API list

Lists all apps:
https://<HOMEY_IP>/api/manager/apps/app

Get single app:
https://<HOMEY_IP>/api/manager/apps/app/<APP_ID>
example: https://<HOMEY_IP>/api/manager/apps/app/nl.nefit.easy

[johan_bendz]

I put together a document on github with all the Endpoints I could find.

Feel free to create an issue with info if you know of any other endpoints or if something is wrong in the document.

JohanBendz/Homey-Endpoints/blob/master/Homey-REST-endpoints

[Niels]

I have no idea how to authenticate local, Using the homey.ink procedure i was able to authenticate on cloud and use all the API’s. As i had trouble finding the needed info here, here is my contribution. Hope this is helpful to someone.

Getting a unlimited key
First step is to get a token that is reusable (longer then 24 Hours), because the API bearer token is only usable for 24 hours and we don’t want to change our code every 24 hours. homey.ink is our solution as it generates a key without an expiration date.

Here we go:

Step 1: Go to https://homey.ink using google chrome.

Step 2: Right click on the page and select inspect(inspecteren) or use Ctrl + Shift + I

Step 3: Select the Network Tab (this will show the network traffic after the authentication is done)

Step 4: Use the “Log In” button and follow the authentication steps.

Step 5: Use the scrollbar if needed, (If you followed this step by step you’ll probably only see one item)

Step 6: select the item named “token, api.athom.com/oauth2”

Step 7: In the headers view scroll down to Form Data, and select the “view source” button.

Step 8: below the “View Source” button the needed key will be shown. Copy it . We’ll need it for the API authentication. it will look something like this:

client_id=09ab2b247cdff0918abfd00d&client_secret=l159fjann0173h2jllsppehg2vj4l28dhhakl3010&grant_type=authorization_code&code=09ab2b247cdff0918abfd00d47cdff0918a2b2414

P.S. This is just an example. your key will look a bit different.

now send the following
POST https://api.athom.com/oauth2/token
Headers:
Content-Type: application/x-www-form-urlencoded
Body
client_id=09ab2b247cdff0918abfd00d&client_secret=l159fjann0173h2jllsppehg2vj4l28dhhakl3010&grant_type=authorization_code&code=09ab2b247cdff0918abfd00d47cdff0918a2b2414

The response will include a refresh token.

To build the “unlimited” key, use the first part of the key, like:

• client_id=09ab2b247cdff0918abfd00d&client_secret=l159fjann0173h2jllsppehg2vj4l28dhhakl3010&grant_type=

• Add: refresh_token&refresh_token=

• and then add the refresh_token (gotten from the authentication above)

The result will look like this:

client_id=09ab2b247cdff0918abfd00d&client_secret=l159fjann0173h2jllsppehg2vj4l28dhhakl3010&grant_type=refresh_token&refresh_token=09ab2b247cdff0918abfd00d47cdff0918a2b2414

This key can be reused in your code to re authenticate yourself every 24 hours without the need to open your brouwer and the former steps.

Getting the bearer token
With the key we got above we can now programmatically get a bearer token.
There are a couple of steps needed to get it, the bearer token is valid for 24 Hours. after 24 Hours you will need to get a new bearer token.

Step 1:
use the KEY you’ve got from Getting a unlimited key as body.

POST https://api.athom.com/oauth2/token
Headers:
Content-Type: application/x-www-form-urlencoded
Body
KEY

Result: will be a Json formatted output. we’ll need the “access_token” value.

Optional Step:
With this request you can get all kind of interesting data, i.e. cloud ID’s and users.
Use the ACCESS_TOKEN gotten in step 1.

GET https://api.athom.com/user/me
Headers:
Authorization: ACCESS_TOKEN

Step 2:
Use the ACCESS_TOKEN gotten in step 1.

POST https://api.athom.com/delegation/token?audience=homey
Headers:
Authorization: ACCESS_TOKEN

Result: A JWT formated token.

Step 3:
Use the JWT_TOKEN gotten in step 2.
Use the CLOUD_ID for your homey, this can also be found in the Optional Step.

POST https://CLOUD_ID.connect.athom.com/api/manager/users/login
Headers:
Content-Type: application/json
Body:
{“token”:“JWT_TOKEN”}

Result: the bearer token that can be used in all API’s

API Test Step
Use the BEARER-TOKEN gotten in step 3
Use the CLOUD_ID for your homey, this can also be found in the Optional Step.

GET https://CLOUD_ID.connect.athom.com/api/manager/devices/device/.
Headers:
Authorization: BEARER-TOKEN

[Rom]

Niels I tried your solution but it is not working. The code parameter I get for oauth2 from the unlimited key (client_id=09ab2b247cdff0918abfd00d&client_secret=l159fjann0173h2jllsppehg2vj4l28dhhakl3010&grant_type=authorization_code&code=09ab2b247cdff0918abfd00d47cdff0918a2b2414)
is only valid for 30 seconds. Did I miss something here?

[Niels]

Hi Rob, welcome to the community. The key that I got from the oauth2 is still valid since I’ve posted. I just started the QT IDE (where I’m trying to develop a embedded system) when running my code it still fully authenticates.

Could you show what’s going on? Don’t show/share your keys.

[Rom]

Hi Niels
Thank you for your fast response.
I get this when I issue the request:
{
“code”: 400,
“error”: “invalid_grant”,
“error_description”: “Invalid code”
}
When I go to homey.ink. Login again I get a new code. When I fill this in, I get the access token as a response. When I do the same again with the same code after about 30 seconds I get the response as above.

[Niels]

Ill do some investigations to see if i get the same issue if i generatie a new key. Weird.

[Rom]

I also tried it using Postman with the same results.

[Niels]

I found the issue but not yet the cause.

In my working key i have “grant_type=refresh_token&refresh_token=”
Now when i follow my own guide i get a key with “grant_type=authorization_code&code=”

Now i’m not so sure how i obtained the key the way i described or if homey had made a change.

I find that authenticating with the key, then use the refresh token in another call will work.
then keep the refresh token to re-authenticate every 24 hours. I’ll update my instructions.

[Niels]

I’m also using postman. this way it’s automatically documented, but not how i got to the first step unfortunately. anyway i’ve just updated my instructions. added an extra step and that seems to work. hopefully it stays working like the key i use in my code.

[Rom]

Thank you very much for your help. This is working now. Now I am finaly able to finish my dashboard for the homey. Still two steps away from fully migrating from Vera Edge to Homey. Every time it gets better. One I am able to do myself (an app for Benext devices, the old one stopped working). For the other one I will have to wait for Athom to fullfill their promise to include a full backup.

[TTXy]

Hello,

I have tried the guidelines over, but it does not work for me… I only get Error code 400:

"code": 400,
"error": "invalid_request",
"error_description": "Invalid or missing grant_type parameter"

I have tried with both curl, PowerShell and Postman…

If this is working for others, I must be doing something wrong… would it be possible to get some screenshot of Postman or commands for cURL… So I know I am posting the right request…

[Niels]

On what request do you get this error. Can you share the packet send, obscure your keys, then I can see what’s going wrong.