Everactive API (v2020-07)

Download OpenAPI specification:Download

Public API to interact with Everactive.

Overview

The Everactive API consists of two modules: a RESTful API for querying and updating data, and webhooks for consuming events related to your equipment.

REST API

The Everactive REST API allows you to perform queries and updates for your equipment monitored by Everactive.

To use the Everactive API you must obtain authorization client credentials. At this time, authorization client credentials are available to Everactive partners and can be obtained by contacting Everactive.

The credentials consist of a client ID and client secret combination. The client ID/client secret combination is only intended for server-side integrations with the Everactive API. The client secret must be protected and hidden from end users. It is the responsibility of developers integrating their backend systems with Everactive to keep the client secret secure.

Authentication

The Everactive REST API uses OAuth2 (https://tools.ietf.org/html/rfc6749) to authenticate requests with two security schemes: client credentials and password.

Client Credentials

The client credentials grant type is used when the system authenticating to the API is not on behalf of a user. Backend system to system integrations shall use the client credentails grant type. An explaination of the client credentials grant type and access token flow can be found at https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/.

Password

The password grant type is used when an authentication request is made on behalf of a user. User-facing clients (such as Everactive's Insights) use the password grant type. An explaination of the password grant type and access token flow can be found at https://www.oauth.com/oauth2-servers/access-tokens/password-grant/.

OAuth2

The Everactive internal API uses OAuth2 to authenticate and generate Bearer token to authenticate and authorize API endpoints.

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: /auth/token
Scopes:
  • super-admin -

    full access to all API endpoints

  • integration-partner -

    access to all public API endpoints

  • customer-admin -

    full access to API endpoints related to the customer the client belongs to

  • user -

    limited access to endpoints related to the customer the client belongs to

password OAuth Flow
Token URL: /auth/token
Refresh URL: /auth/token
Scopes:
  • super-admin -

    full access to all API endpoints

  • customer-admin -

    full access to API endpoints related to the customer the client belongs to

  • user -

    limited access to endpoints related to the customer the client belongs to

Request / Response body

All Everactive API requests and responses use JSON for the body*. No other data formats are accepted or provided (e.g. XML).

* OAuth2 Authentication endpoints require a form for the body (Content-Type: application/x-www-form-urlencoded) as per the specification.

Response Body Wrapper

All responses are wrapped in an object with the primary payload in the data property. Additional properties may be provided depending on the type of payload returned, specifically error conditions and pagination information for lists of data.

Pagination Info

Responses returning lists of data will have an Array in the data property and an additional paginationInfo object with the following format:

{
  "paginationInfo": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 153,
    "totalPages": 4
  }
}

Errors

Requests that result in an error condition will have the following format (Note: the values provided are an example, specific errors result in specific code and message values):

{
  "code": "error_validation",
  "message": "Validation error.",
  "errors": [
    "code": "err_invalid_mac_address",
    "field": "sensor.macAddress",
    "message": "no:ta:re:al:ma:c0 is an invalid MAC Address"
  ]
}

Webhooks

The Everactive API allows clients to subscribe to updates for certain events.

When an event is detected, Everactive's webhook sends a an HTTP POST request to an endpoint you designated when creating your subscription. The details specific to the event are transferred as a JSON payload in the POST body.

Security

Webhook endpoints are required to use HTTPS. Additionally, all subscriptions are saved with a generated webhook secret. The generated secret is used to sign the request using http signatures (https://tools.ietf.org/id/draft-cavage-http-signatures-12.html). You must store the generated secret and validate each POST received was signed correctly using the secret.

Each request body is hashed using an SHA-256 algorithm with the webhook secret as the key and sent as the Digest header. The Digest header is used as part of the signature, and can also be used to verify the request used the correct webhook secret.

Signature Verification Details

Given the following request (body is omitted)

POST / HTTP/1.1
Content-Length: 385
Date: Sun, 27 Sep 2020 06:25:56 EDT
Digest: SHA-256=CUqnzEfLL8k73aT7e1R55yCQ6VAM70ZfDg9AMzJvPHM=
Host: localhost:3000
Signature: keyId="subscription-id-1",algorithm="hmac-sha256",
    signature="m7lO3Xld1ESjZTMX+Hg2njRXTQO3QK342dHd2x7Dbo0=",
    headers="(request-target) date digest host content-length"

The receiving client should construct a signing string as follows (+ "\n" added for clarity):

(request-target) post / + "\n"
date: Sun, 27 Sep 2020 06:25:56 EDT + "\n"
digest: SHA-256=CUqnzEfLL8k73aT7e1R55yCQ6VAM70ZfDg9AMzJvPHM= + "\n"
host: localhost:3000 + "\n"
content-length: 385

Using the secret provided when the subscription was created, hash the above string using sha256 and compare the hash generated on the client with the signature value provided in the Signature header. If they do not match the request is not valid.

To prevent replay attacks the Date header should be checked against the actual time with an allowance for clock skew. Since there is no hard rule for an allowable amount of time offset, it's recommended to reject any requests where the Date header is off by more than 300 seconds in either direction from the current time.

Specifics will be language dependent. There are also libraries available to verify http signatures. Everactive has used the following libraries:

Others are available, covering many languages.

Webhook Event Types

Everactive offers one event type for a webhook subscription at this time.

Steam Trap State Change

The Steam Trap State Change event is triggered when the state of a monitored trap changes (e.g. Good to Blowthrough). The Everactive API will POST the following body when this event is triggered:

{
    "eventId": "state-change-event-id-1",
    "eventTimestamp": 1600878991,
    "integrationInfo": {
      "assetId": "asset-id-1",
      "name": "Asset 1"
    },
    "facility": "facility",
    "location": "location",
    "sensorMacAddress": "ca:fe:00:01:02:03",
    "serviceTag": "service-tag",
    "trapEndState": "Blowthough",
    "trapDetailUrl": "https://api.data.everactive.com/v2020-07/steamtraps/steam-trap-id",
    "trapID": "steam-trap-id",
    "trapInsightsUrl": "https://insights.everactive.com/steamtrap/steam-trap-id",
    "trapStartState": "Good"
}

Note: The integrationInfo property is optional, and will be populated with the assetId and name properties you provided via the Everactive REST API when the steam trap was created or updated. If these properties were never set, integrationInfo will be omitted.

Valid steam trap states:

  • Blowthrough - Failure
  • Good - Good
  • Intermittent Blowthrough - Light - Light
  • Intermittent Blowthrough - Medium - Medium
  • Intermittent Blowthrough - Heavy - Heavy
  • Leaking By - Leaking
  • Unexpected Cold Condition - Cold

Gateway

Endpoints and components related to gateways.

get gateways

Return a list of gateways the client is authorized to view. Super-admin type users will receive all gateways unless the customerId query parameter is included in the request.

Authorizations:
OAuth2 (super-admincustomer-adminuserintegration-partner)
query Parameters
id
string
Example: id=bcf992bf-bb5e-410d-bd9e-a25c2f563ca4

Filter the gateways returned by the gateway id. An exact match is used for this filter.

location
string
Example: location=mezzanine

Filter the gateways using a LIKE comparison with the location property.

name
string
Example: name=East Mezzanine 3AG32B5

Filter the gateways using a LIKE comparison with the name property.

page
required
integer <int32> >= 1
Default: 1
Example: page=1

The page number to return from a paginated endpoint. One-based.

pageSize
integer <int32> >= 1
Default: 50
Example: pageSize=25

The maximum number of items to return per page.

serialNumber
string
Example: serialNumber=3AG32B5

Filter the gateways using a LIKE comparison with the serialNumber property.

sortBy
string
Default: "lastReading"
Enum: "autoAuthorizeExistingSensors" "canSupportEvernet2" "configSchema" "customer.name" "deploymentStatus" "enableSSH" "enableWakeup" "evernet1Settings.enabled" "id" "lastReading" "location" "name" "serialNumber" "status"
Example: sortBy=lastReading

Indicate what field should be used to sort the returned list of gateways. If omitted the gateway's are returned with a descending sort order on the lastReading timestamp.

sortDir
string
Enum: "asc" "desc"
Example: sortDir=asc

The direction to sort the list of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "paginationInfo": {
    }
}

Machine

Endpoints and components related to machines.

get machines

Retrieve a list of machines the user is authorized to view. The returned list of machines can be filtered by various fields using optional query parameters. If more than one filter value is included the filtering is combined with an and statement meaning the returned traps must meet all filtering criteria.

Authorizations:
OAuth2 (super-admincustomer-adminuserintegration-partner)
query Parameters
alarmState
string
Enum: "Good" "Acknowledged" "Alarm"

Filter the machines returned by their current alarm state. Allowed values are Good, Acknowledged, and Alarm. Multiple values can be passed as a comma separated value (e.g. &alarmState=Good,Acknowledged).

alarmStateUserName
string
Example: alarmStateUserName=pat

Filter the machines returned by the alarmStateUserName property. The value is filtered using a LIKE comparison statement.

equipmentName
string
Exam