This resource becomes available after a user has successfully authenticated with the API service.

Endpoints

The User Session Info object

  • userIdinteger

    ID of the user associated with this session.

  • appIdstring

    App used to initiated this session.

  • projectIdinteger

    Project associated with this session.

  • creationTimestring| format is date-time

    Time when session started.

The User Session Info object

{
    "userId": 1920,
    "appId": "controller_app",
    "projectId": 3428,
    "creationTime": "2019-12-17T19:53:44.626Z"
}

Get user session info

Endpoint
get /userSession
Description

Get info about the current user session.

Authorization Headers What's this?

Must contain API key of a user.

Response
  • 200Successful retrieval of current user session.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 404The requested userSession does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

{
  "userId": 1874,
  "appId": "controller_app",
  "projectId": 1264,
  "creationTime": "2019-12-17T19:53:44.626Z"
}

Terminate user session

Endpoint
delete /userSession
Description

Terminate a user session. The associated API key will also be invalidated.

Authorization Headers What's this?

Must contain API key of a user.

Response
  • 204User session terminated. There is no return body.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The required userSession does not exist or is not accessible.
  • 409The userSession cannot be deleted because it is being used by another part of the system.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Listen to events

Endpoint
get /userSession/websocket
Description

Establish a WebSocket connection and listen for events. Any non-WebSocket requests will be rejected. Once the connection is established, the client can expect incoming messages in the form of Event JSON objects. Use the homeId or deviceId query parameter to limit what events to be sent through the conenction. (If both homeId and deviceId parameters are present at the same time, only deviceId will take effect.) Since not all WebSocket client implementations allow you to set the Authorization HTTP header, you can pass the user API key as the authToken query parameter. This API call is not allowed for BYOU projects.

Authorization Headers What's this?

Must contain API key of a user.

Query Parameters
  • homeId

    integer

    If this parameter is present, only events for the specified home will be sent through this WebSocket connection. This parameter can be used multiple times to capture events for multiple homes.

  • deviceId

    integer

    If this parameter is present, only events from the specifieddevice will be sent through this WebSocket connection. This parameter can be used multiple times to capture events from multiple devices.

  • authToken

    string

    User API key. Needed only if the Authorization header cannot be set.

Response
  • 101Successfully established a WebSocket connection.
  • 401Authorization is required to access this resource.
  • 403Request failed because of invalid data or denied permission.
  • 404The requested resource does not exist or is not accessible.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.