The main goal of athom-api is to provide easy access to Homeys and their functions. Athom-api can be used in most javascript enabled environments, like webbrowsers, node.js applications, but also inside Homey Apps and react-native applications.

Connecting to Homey (remotely)

Connecting to Homey is a two-step process. First of all we need our user to log-in using their Athom Account using AthomCloudAPI, then we can retrieve the Homeys we have access to (usually the user grants access to exactly 1 Homey). And finally, we can start an authenticated session on this Homey. An authenticated session on Homey is represented by HomeyAPI.

//Web-side
//When using the CDN script include, all top-level exports are globally 
// available, so no includes are neccesarry.

//When using a package manager such as npm or yarn and mjs and a transpiler,
// we need to install athom-api and use the following import:
//import {AthomCloudAPI, AthomStorageAdapter} from 'athom-api';

//When using cjs and a transpiler we need to use the following import:
//const {AthomCloudAPI, AthomStorageAdapter} = require('athom-api');


//This sets a global config 
// Alternatively these values can be supplied to the constructor 
AthomCloudAPI.setConfig({
    clientId: "_client_id_", //Obtained through the developer portal/Athom
    clientSecret: "_client_secret_", //Obtained through the developer portal/Athom
    redirectUrl: 'http://localhost:8080' //Configured through developer portal
});

//Create a new AthomCloudAPI instance
const cloudAPI = new AthomCloudAPI({
    //CloudAPI can use a store to persist and cache session data.
    // In this example we want to use HTML5 localStorage to do this.
    // Alternatively you can extend AthomStorageAdapter and implement
    //  your own storage engine instead.
    // If no store is specified, and HTML5 local storage is available, 
    //  it is selected automatically.
    store: new AthomStorageAdapter.LocalStorage('_athom_cloud_api')
});


//This function attempts to log-in to a specific homey and returns a HomeyAPI
async function login() {
    //Check if we are logged in
    if(!await cloudAPI.isLoggedIn()) {

        //If we are not logged in but do have an OAuth2 authorization code 
        // parameter in our URL, use it to authenticate
        if(cloudAPI.hasAuthorizationCode()) {
            await cloudAPI.authenticateWithAuthorizationCode();
        } else {
            //Redirect the user to the OAuth2 login page
            window.location.href = cloudAPI.getLoginUrl([
                'account.homeys.readonly', //required to access homey
                'homey.manager.flows.readonly' //required to read flows
            ]);
        }
    }

    //Retrieve information about the currently logged in user
    //In some cases you may want to prefer a locally cached 
    // version using getAuthenticatedUserCached. 
    // Using a cached user is useful in situations where 
    // internet connectivitity is not always available
    const user = await cloudAPI.getAuthenticatedUser();
    console.info('User', user.fullname, 'Authenticated');

    //Get the first homey of this user
    const homey = user.getFirstHomey();

    //Start a session on this Homey
    console.info('Logging in to:', homey.name);
    const homeyAPI = await homey.authenticate();

    console.info('homeyAPI created');

    //Example: Make the Homey say something to prove we're authenticated
    await homeyAPI.speechOutput.say({text: 'Hello: '+user.fullname});

    return homeyAPI;
}

login();

Connecting to Homey in a Homey app

It is also possible to use the web API inside an Homey app. This gives you access to a HomeyAPI that has access to the Homey the app is currently running on. In order to use this functionality, please make sure to include the homey:manager:api permission in your app.

const HomeyAPI = require('athom-api');

async function login() {

    //Authenticate against the current Homey.
    const homeyAPI = await HomeyAPI.forCurrentHomey();

    //Example: Make the Homey say something to prove we're authenticated
    await homeyAPI.speechOutput.say({text: 'Hello: '+user.fullname});

    return homeyAPI;
}

login();