Homey Pro (Early 2023) offers a feature called API Keys, that's intended for hobbyists and developers to create integrations with their Homey Pro.
1. Creating the API Key
To create an API Key, navigate to Settings → API Keys in the Homey Web App. Tap New API Key, give it a name, and select the permissions it should have.
Tap Create, and copy the API Key to a safe place. For security reasons, you won't be able to see it again!
💡 Tip: You can revoke the API Key at any time in the Homey Web App.
2. Using the API Key
Visit the Web API Reference to learn everything you can do with your API Key.
2a. Use the API Key in a Node.js application
The most common way to use your API Key, is to create a program.
First, create a new project.
$ npm init
$ npm i homey-api@3.0.0-rc.15
Then, write some 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
}
💡 Tip: You could also use mDNS/Bonjour as address. Use http://homey-507f191e810c19729de860ea.local
, where 507f191e810c19729de860ea
is your Homey's ID.
2b. Use the API Key in HTTP
Homey Pro has a Web API accessible with HTTP. To authenticate, simply add a header to your API call.
GET /api/manager/devices/device/ HTTP/1.1
Host: 192.168.0.123
Authorization: Bearer <your api key>
💡 Tip: to use HTTPS, use https://192-168-0-123.homey.homeylocal.com
as hostname.