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.

Request Headers What's this?
  • Authorization

    required

    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.

Request Headers What's this?
  • Authorization

    required

    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 one of the homeId, deviceId, or entityId query parameter to limit what events to be sent through the connection. If both homeId and deviceId parameters are present at the same time, only deviceId will take effect. Also, if both deviceId and entityId parameters are present at the same time, only entityId will take effect.

One query parameter is required if the project is configured to use the permission-based access control. To receive home events with the homeId parameter, the user requires read permission for home events of the home. To receive device events with the deviceId parameter, the user requires read permission for the device. To receive entity events with the entityId parameter, the user requires read permission for entity events of the entity.

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.

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 specified device will be sent through this WebSocket connection. This parameter can be used multiple times to capture events from multiple devices.

  • entityId

    string

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

  • authToken

    string

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

Request Headers What's this?
  • Authorization

    required

    Must contain API key of a user.

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.