Articles in this section

See more

Getting started with API Keys

  • Updated

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.

API_Keys.png

Tap Create, and copy the API Key to a safe place. For security reasons, you won't be able to see it again!

 

Created.png

💡 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.

Related articles