HTTP Specification

While we provide a fully featured Web API Client for JavaScript (Browser, Node.js) environments, we understand that you might prefer another programming language. This guide is to help you get started with the core concepts to build your own Web API connection by only using HTTP + Socket.io.

Authenticating with Athom Cloud API

The Homey Web API uses OAuth2 to authorise Homey users with your OAuth2 client. They give your application delegated permission to act on their behalf.

Step 1 — Getting an Authorization Code

First, your application needs to redirect a user to https://api.athom.com/oauth2/authorise with the following query parameters:

Name	Value
authorization_type	code
client_id	Your Client ID
redirect_uri	Your Redirect URI
state	Optional. This can be any string, and will be returned once the user has been redirected to your Redirect URI.

For example:

https://api.athom.com/oauth2/authorise?authorization_type=code&client_id=abcd&redirect_uri=https://example.com/oauth2/callback&state=my_state

Once the user has approved the request, they will be redirected to your client's Redirect URI, with the code query parameter.

For example:

https://example.com/oauth2/callback?code=abcdef&state=my_state

Step 2 — Exchanging the Authorization Code for a Token

In the back-end of your app, you can now exchange the Authorization Code for a Token. The Authorization Code is valid for only 30 seconds, whereas the Token will be valid forever, or until the user revokes it.

Your back-end should make a HTTP POST request to https://api.athom.com/oauth2/token with the following application/x-www-form-urlencoded parameters.

URL

https://api.athom.com/oauth2/token

Headers

Name	Value
Content-Type	application/x-www-form-urlencoded
Authorization	Basic base64(Client ID + ':' + Client Secret)

Body

Name	Value
grant_type	authorization_code
authorization_code	The code you retrieved in Step 1.

For example, the HTTP request should look like this:

POST /oauth2/token HTTP/1.1
Authorization: Basic ZXhhbXBsZTpleGFtcGxl
Content-Type: application/x-www-form-urlencoded
Host: api.athom.com
Connection: close
Content-Length: 56

grant_type=authorization_code&authorization_code=example 

When successful, the result will be a JSON-encoded object that looks like this:

{
  "token_type": "bearer",
  "grant_type": "authorization_code",
  "access_token": "abc...",
  "refresh_token": "abc...",
  "expires_in": "3660"
}

You can now make API calls to https://api.athom.com with a header Authorization: Bearer <access_token>.

Step 3 — Refreshing the Token

For security purposes, the access token will expire after one hour. The refresh token will never expire, unless a user revokes your client's access to their account, or no API call has been made for 6 months.

Once your access token has expired, the Web API will respond with a 401 Unauthorized error.

To refresh the token, make the following HTTP call:

URL

https://api.athom.com/oauth2/token

Headers

Name	Value
Content-Type	application/x-www-form-urlencoded
Authorization	Basic base64(Client ID + ':' + Client Secret)

Body

Name	Value
grant_type	refresh_token
refresh_token	The refresh_token you retrieved in Step 2.

For example, the HTTP request should look like this:

POST /oauth2/token HTTP/1.1
Authorization: Basic ZXhhbXBsZTpleGFtcGxl
Content-Type: application/x-www-form-urlencoded
Host: api.athom.com
Connection: close
Content-Length: 56

grant_type=refresh_token&refresh_token=abc... 

When successful, the result will be a JSON-encoded object that looks like this:

{
  "token_type": "bearer",
  "grant_type": "authorization_code",
  "access_token": "abc...",
  "refresh_token": "abc...",
  "expires_in": "3660"
}

Make sure to save the entire new token, and not only the new access token, because the refresh token might have also changed.

Authenticating with Homey

Once you have authenticated with Athom Cloud API, you can view a user's information and their Homeys. But before you can communicate with a Homey itself, such as list devices and start Flows, you need to create a session on that Homey.

Step 1 — Get a user's Homeys

First, you can get a list of a user's information and their Homeys.

GET https://api.athom.com/user/me
Authorization: Bearer <access token>

This will return a JSON object, for example:

{
  "_id": "688770a242d4006cf3cf0216",
  "email": "[email protected]",
  "firstname": "John",
  "lastname": "Doe",
  "homeys": [
    {
      "_id": "688770c8189ccd274b5a8bfe",
      "name": "John's Homey Pro",
      "platform": "local", // can be either 'local' for Homey Pro, or 'cloud' for Homey Cloud
      "localUrl": "http://192.168.1.100",
      "localUrlSecure": "https://192-168-1-100.homey.homeylocal.com",
      "remoteUrl": "https://688770a242d4006cf3cf0216.homey.eu-west-1.homeypro.net",
      // ...
    }
  ],
  // ...
}

Depending on whether your integration lives in the user's LAN network or in the cloud, choose localUrlSecure , localUrl or remoteUrl respectively. When you have the option of connecting locally, always prefer localUrlSecure over localUrl over remoteUrl in that order for speed & security.

All of these URLs can change over time, and become null. You can cache them, but never rely solely on them. Make the GET /user/me again to get the latest URLs.

Step 2 — Obtain a Delegation Token

Second, you need to create a delegation token. This is a JSON Web Token (JWT) with the homey audience. This will let Homey know that you have delegated access to that Homey.

POST https://api.athom.com/delegation/token?audience=homey
Authorization: Bearer <access token>

This will return a JSON string, e.g. "abc..." in the body. This is your delegation token.

Step 3 — Creating a Session on Homey

Finally, make a HTTP request to the user's Homey:

POST https://688770a242d4006cf3cf0216.homey.eu-west-1.homeypro.net/api/manager/users/login
Content-Type: application/json

{
  "token": "<delegation token>"
}

This will return a JSON string, which is the session token for this Homey. For example, "abc...". You can use this string when making API calls to this Homey.

Once this session expires, Homey will reply with a 401 Unauthorized status code.

Step 4 — Making API calls to Homey

You are now ready to make API calls to Homey!

For example, to get a list of devices (if your Client has the devices.readonly scope).

GET https://688770a242d4006cf3cf0216.homey.eu-west-1.homeypro.net/api/managewr/devices/device
Authorization: Bearer <session token>

This will return a JSON list of devices:

{
  "abc...": {
    "id": "abc...",
    "name": "Kitchen Light",
    "class": "light",
    "capabilities": ["onoff", "dim"],
    // ...
  }
}

---

Now head over to the Web API Reference for Homey Cloud & Homey Pro to further develop your app. If you're interested in receiving realtime events, head over to Socket.io Specification.