AthomCloudAPI

Represents the entire Athom Cloud API

Constructor

new AthomCloudAPI(opts)

Parameters:
Name Type Description
opts object An options object
Properties
Name Type Attributes Description
clientId string <optional>
The OAuth2 clientID
clientSecret string <optional>
The OAuth2 clientSecret
redirectUrl string <optional>
The OAuth2 redirectUrl
store AthomStorageAdapter <optional>
A persistent store for session data. (defaults to HTML5 LocalStorage if available)
autoRefreshTokens boolean <optional>
Set to false to disable automatic token refreshing (defaults to true)
baseUrl string <optional>
A custom baseUrl

Methods

async createUser(optsopt) → {AthomCloudAPI.User}

Add a user.

Required OAuth scopes:
- account.user:su

Parameters:
Name Type Attributes Description
opts object <optional>
Named parameters
Properties
Name Type Attributes Description
user object User data.
Properties
Name Type Description
firstname string
lastname string
email string
password string
language string
newsletter boolean <optional>
Set to true to subscribe to newsletter
gettingStarted boolean <optional>
Set to false to prevent Getting Started e-mails
Returns:
AthomCloudAPI.User - The newly created user

async getUser(optsopt) → {AthomCloudAPI.User}

Get a user

Required OAuth scopes:
- account.user

Parameters:
Name Type Attributes Description
opts object <optional>
Named parameters
Properties
Name Type Description
id string User ID.
Returns:
AthomCloudAPI.User - User data.

async updateUserDevice(optsopt) → {AthomCloudAPI.UserDevice}

Update user device data.

Required OAuth scopes:
- account.user

Parameters:
Name Type Attributes Description
opts object <optional>
Named parameters
Properties
Name Type Description
userId string User ID.
deviceId string Device ID.
device AthomCloudAPI.UserDevice Device data to update.
Returns:
AthomCloudAPI.UserDevice - The updated device.

async deleteUserDevice(optsopt)

Delete user device data.

Required OAuth scopes:
- account.user

Parameters:
Name Type Attributes Description
opts object <optional>
Named parameters
Properties
Name Type Description
userId string User ID.
deviceId string Device ID.

async getAuthenticatedUser(optsopt) → {AthomCloudAPI.User}

User associated with provided credentials.

Required OAuth scopes:
- account.user.readonly

Parameters:
Name Type Attributes Description
opts object <optional>
Named parameters
Properties
Name Type Attributes Description
additionalScopes string <optional>
Comma seperated list of additional scopes to require.
Returns:
AthomCloudAPI.User - Associated user account

async updateHomey(optsopt) → {AthomCloudAPI.Homey}

Update a Homey

Required OAuth scopes:
- account.homeys

Parameters:
Name Type Attributes Description
opts object <optional>
Named parameters
Properties
Name Type Description
id string The Homey Cloud ID.
homey AthomCloudAPI.Homey Homey data to update.
Returns:
AthomCloudAPI.Homey - The updated Homey

async getAuthenticatedUserCached() → {AthomCloudAPI.User}

A cached version of getAuthenticatedUser.
If no cached version is available, this call invokes getAuthenticatedUser.
The cached version only contains a subset of the AthomCloudAPI.User properties, and has a _cached: true property to indicate the User might be outdated.

async isLoggedIn() → {boolean}

Returns true if the user is logged in, false otherwise. Attempts to refresh tokens if needed.
Returns:
boolean

async logout(token)

Logs out from the Athom API
Parameters:
Name Type Description
token AthomCloudAPI.Token An OAuth2 auth token object
Fires:

async setToken(token) → {AthomCloudAPI.Token}

Sets the authentication status of the API
Parameters:
Name Type Description
token AthomCloudAPI.Token An OAuth2 auth token object
Fires:
Returns:
AthomCloudAPI.Token - The (possibly refreshed) authTokens object or null if the token was invalid

hasAuthorizationCode() → {boolean}

Returns true if an authorization code is present
Returns:
boolean - true if an authorization code is present as query parameter

hasDelegatedLogin() → {boolean}

Returns true if a delegated login is present. If true, getLoginUrl() will return an url that automatically authenticates the delegated user.
Returns:
boolean - true if a delegtion token is present as query parameter

async authenticateWithAuthorizationCode(authorizationCodeopt) → {AthomCloudAPI.Token}

Authenticate using an oauth2 authorizationCode
Parameters:
Name Type Attributes Description
authorizationCode string <optional>
Returns:
AthomCloudAPI.Token - The authState object

async authenticateWithClientCredentials() → {AthomCloudAPI.Token}

Authenticate using client-credentials only
Returns:
AthomCloudAPI.Token - The authState object

async getDelegatedLoginUrl(opts) → {string}

Returns an URL to a third party service with appended preselection options
Parameters:
Name Type Description
opts object options
Properties
Name Type Attributes Description
baseUrl string The URL to the third party service
resource string <optional>
Requested Resource (if already known)
state string <optional>
The oAuth state parameter for the third party service (if required)
audience string <optional>
The delegation audience (if required)
meta string <optional>
The delegation claim metadata (if required)
Returns:
string - Url to the login page

getLoginUrl(optsopt) → {string}

Returns an URL to the OAuth2 login page
Parameters:
Name Type Attributes Description
opts object <optional>
options
Properties
Name Type Attributes Description
scopes Array.<string> <optional>
Requested Scopes (if subset from client scopes)
resource string <optional>
Requested Resource (if already known)
state string <optional>
State query parameter provided to callback
userToken string <optional>
User Delegation token to skip selection of users
Returns:
string - Url to the login page

enableAutoRefreshTokens()

Enables automatic access token token refreshing

disableAutoRefreshTokens()

Disables automatic access token token refreshing

async refreshTokens(tokenopt) → {AthomCloudAPI.Token}

Force a refresh of the API tokens
Parameters:
Name Type Attributes Description
token string <optional>
The refresh token to use instead of the internal one.
Returns:
AthomCloudAPI.Token - The authState object

static setConfig(opts)

Sets the global client configuration, can be overridden
Parameters:
Name Type Description
opts object An options object
Properties
Name Type Description
clientId string The OAuth2 clientID
clientSecret string The OAuth2 clientSecret
autoRefreshTokens boolean Set to false to disable automatic token refreshing

Events

logout

Emits when the Authorization token has expired and cannot be refreshed without user interaction. Alternatively, it is also possible to listen for the token event and check for null.

Classes

Error

Token

Role

UserProfile

Avatar

User

UserDevice

Homey