AthomCloudAPI

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.StorageAdapterNodeJS
}

Example

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

// Create an AthomCloudAPI instance
const api = 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 api.isLoggedIn();
if (!loggedIn) {
  if (api.hasAuthorizationCode()) {
    const token = await api.authenticateWithAuthorizationCode();
  } else {
    window.location.href = api.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();

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

Classes

Methods

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>