Articles in this section

Create and use API Keys on Homey Pro

  • Updated

API Keys let you build custom integrations with Homey Pro. They’re intended for hobbyists and developers who want to connect Homey to external tools or applications.

1. Create an API Key

In the Homey Web App, go to Settings → API Keys and click New API Key. Give it a name and select the permissions it needs, then click Create.

API_Keys.png

Copy the API Key and store it somewhere safe. You won’t be able to view it again after closing this screen.

 

Created.png

Tip 
You can revoke an API Key at any time in the Homey Web App.

2. Use the API Key

Visit the Web API Reference to see everything you can do with your API Key.

Using the API Key in a Node.js application

The most common approach is to use the API Key in a Node.js application. First, create a new project:

$ npm init
$ npm i homey-api@3.0.0-rc.15

Then write your code:

import { HomeyAPI } from 'homey-api';
const homeyApi = await HomeyAPI.createLocalAPI({
  address: 'http://192.169.1.123', // Replace this with Homey Pro's IP address
  token: 'ba78f646-4a0f-4869-95cd-c7040bc4e63b:21b9f8d2...', // Replace this with your API Key
});

// Get all devices
const devices = await homeyApi.devices.getDevices();
for(const device of Object.values(devices)) {
  console.log(device.name); // Prints the device's name
}

You could also use mDNS/Bonjour as the address. Use http://homey-507f191e810c19729de860ea.local, replacing 507f191e810c19729de860ea with your Homey’s ID.

Using the API Key over HTTP

Homey Pro has an HTTP Web API. To authenticate, add an authorization header to your request:

GET /api/manager/devices/device/ HTTP/1.1
Host: 192.168.0.123
Authorization: Bearer <your api key>

To use HTTPS, use https://192-168-0-123.homey.homeylocal.com the hostname.

Related articles