AthomCloudAPI

new AthomCloudAPI(optsopt)

The AthomCloudAPI class can be used to authenticate a user with your client, and login on that user's Homey.

This API is available at https://api.athom.com/

Parameters

Name	Type	Description
`opts`	object <optional>
`baseUrl`	string <optional> default:`https://api.athom.com/`	The Base URL of the API. Set `ATHOM_CLOUD_API_BASEURL=http://...` as environment variable on Node.js, or in `window.localStorage` on browsers to override.
`debug`	boolean <optional> default:`false`	Send debug messages to `console.log` if set to `true`. Set `ATHOM_CLOUD_API_DEBUG=1` as environment variable on Node.js, or in `window.localStorage` on browsers to override.
`secret`	secret <optional>	A shared secret for APIs with a `secret` parameter in an endpoint. Set `ATHOM_CLOUD_API_SECRET=...` as environment variable on Node.js, or in `window.localStorage` on browsers to override.
`clientId`	string
`clientSecret`	string
`redirectUrl`	string
`autoRefreshTokens`	boolean <optional> default:`true`
`token`	AthomCloudAPI.Token <optional> default:`null`
`store`	AthomCloudAPI.StorageAdapter <optional> default:`AthomCloudAPI.StorageAdapterBrowser or AthomCloudAPI.StorageAdapterMemory`
}

Example

const AthomCloudAPI = require('homey-api/lib/AthomCloudAPI');

// Create an AthomCloudAPI instance
const cloudApi = new AthomCloudAPI({
  clientId: '5a8d4ca6eb9f7a2c9d6ccf6d',
  clientSecret: 'e3ace394af9f615857ceaa61b053f966ddcfb12a',
  redirectUrl: 'http://localhost',
});

// Check if we're logged in
// If not, redirect the user to the OAuth2 dialog
const loggedIn = await cloudApi.isLoggedIn();
if (!loggedIn) {
  if (cloudApi.hasAuthorizationCode()) {
    const token = await  cloudApi.authenticateWithAuthorizationCode();
  } else {
    window.location.href =  cloudApi.getLoginUrl();
    return;
  }
}

// Get the logged in user
const user = await cloudApi.getAuthenticatedUser();

// Get the first Homey of the logged in user
const homey = await user.getFirstHomey();

// Create a session on this Homey
const homeyApi = await homey.authenticate();

// Get all Zones from ManagerZones
const zones = await homeyApi.zones.getZones();

// Get all Devices from ManagerDevices
const devices = await homeyApi.devices.getDevices();

// Turn all devices on
for(const device of Object.values(devices)) {
  // Turn device on
  await device.setCapabilityValue({
    capabilityId: 'onoff',
    value: true,
  });
}

Classes

Instance Methods

authenticateWithAuthorizationCode

(async) authenticateWithAuthorizationCode(optsopt): Promise.<AthomCloudAPI.Token>

Authenticate with an authorization code.

Parameters

Name	Type	Description
`opts`	Object <optional>
`code`	String	Default to `?code=...` when in a browser.
`removeCodeFromHistory`	Boolean <optional> default:`true`	Remove `?code=...` from the URL in the address bar.
}

Returns

Promise.<AthomCloudAPI.Token>

getAuthenticatedUser

(async) getAuthenticatedUser(opts)

HTTP

GET /user/me

Parameters

Name	Type	Description
`opts`	object
`additionalScopes`	string <optional>	In `query`
}

getAuthenticatedUser

(async) getAuthenticatedUser(optsopt): Promise.<AthomCloudAPI.User>

Get the current authenticated AthomCloudAPI.User

Parameters

Name	Type	Description
`opts`	object <optional>
`$cache`	object <optional> default:`true`	Use the cache
}

Returns

Promise.<AthomCloudAPI.User>

getLoginUrl

getLoginUrl(optsopt): string

Get a login URL to redirect the user to (MyApp wants access to ...).

Parameters

Name	Type	Description
`opts`	object <optional>
`state`	string <optional>	A state parameter for enhanced security.
`scopes`	Array.<string> <optional>	An array of scopes. By default, the client's scopes will be used.
}

Returns

The login URL to redirect the user to.

string

hasAuthorizationCode

hasAuthorizationCode(): boolean

Checks if the current URL in the browser has a ?code=... parameter.

Returns

boolean

isLoggedIn

(async) isLoggedIn(): Promise.<boolean>

Checks if the current token is valid, and if the user is logged in.

Returns

Promise.<boolean>

logout

(async) logout(): Promise.<void>

Logout and delete the local token.

Returns

Promise.<void>