Homey Community Forum

[Unsupported] Homey v2 REST API

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…

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": {}

Yes, but thanx anyway.

I have two entries for the API list

Lists all apps:

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

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.


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:


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
Content-Type: application/x-www-form-urlencoded

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:


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
Content-Type: application/x-www-form-urlencoded

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
Authorization: ACCESS_TOKEN

Step 2:
Use the ACCESS_TOKEN gotten in step 1.

POST https://api.athom.com/delegation/token?audience=homey
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
Content-Type: application/json

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/.
Authorization: BEARER-TOKEN


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?

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.

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.

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

I also tried it using Postman with the same results.

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.

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.

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.


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…

1 Like

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.

I am able to get the token information from from homey.ink, like:


Then I try to use curl with the following command on the first request:

curl -d “client_id=5cbbXXXXXXXXXX009fXXXXe46&client_secret=gvhs0gXXXXxxxxXXXXxxxXXkuo1uvs8&grant_type=authorization_code&code=9c64eXXXXXXXXXXXXXXXXX584da7” -H “Content-Type: application/x-www-form-urlencoded” -X POST https://api.athom.com/oauth2/token

Then I get the response mentioned over…

Works fine for me (on macOS):

$ curl -d 'client_id=5cbb504da1fc782009f52e46&client_secret=gvhs0gebgir8vz8yo2l0jfb49u9xzzhrkuo1uvs8&grant_type=authorization_code&code=XXX' -H 'content-type: application/x-www-form-urlencoded' -XPOST https://api.athom.com/oauth2/token

Just tried one more time, now I got this:

{“code”:400,“error”:“invalid_grant”,“error_description”:“Code has expired”}

I will try close down the browser and clear cache and try one more time…

That means that you weren’t quick enough :wink: The code that you cut-and-paste from the browser has a very short expiry time.

1 Like