API Documentation

This is the Inexogy REST API, providing access to meters and measurements maintained by Inexogy.

The base URL for all endpoints is https://api.inexogy.com/public/v1. Endpoints must be accessed exclusively through HTTPS. Authentication to data endpoints happens via the OAuth 1.0 protocol with the HMAC-SHA1 signature method. If HTTP return codes indicate that an access token is not valid anymore, the authorization process described below must be repeated.

Meter identifiers must be of the form meterId which is returned by the meters endpoint.

Many endpoints return human-readable error messages as text/plain if there are parameter or authorization problems. Clients must set the HTTP Accept header to include text/plain in order to receive those messages.

This interface and its documentation are preliminary and as such subject to change without notice. Invocation rate limits may apply to data endpoints.

For questions, please contact api@inexogy.com. Please include the serial number(s) of the meter(s) you want to query and the e-mail address which you use to access the API.

Download Java API demo client

Full example with authorization

Note: All requests are made to api.inexogy.com over TLS.

Client registration

To prepare for API access, first register your client application to obtain a consumer token.

Request
POST /public/v1/oauth1/consumer_token
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Content-Type: application/x-www-form-urlencoded
  
  client=MyOwnClient
Response
{"key":"btgd2cg2bm3lbjqsfv150fj9q8","secret":"nequdoe1msgb96pn20gn4jof0g","owner":"MyOwnClient","attributes":{},"principal":null}

Obtain request token

Note: Subsequent authorization steps follow the OAuth 1.0 standard. Any OAuth 1.0-compatible client library should perform these steps automatically.

Next, a request token for the application must be obtained using the consumer key from the above response.

Request
POST /public/v1/oauth1/request_token
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Authorization: OAuth
      oauth_consumer_key="btgd2cg2bm3lbjqsfv150fj9q8",
      oauth_signature_method="HMAC-SHA1",
      oauth_timestamp="1467792887",
      oauth_nonce="9fd50a6f-40e0-41be-8809-34aa832b688e",
      oauth_callback="oob",
      oauth_signature="hcE6Q3boTytkHmM72xegCP1Y3W4%3D"

Note the message signature which must be made using the HMAC-SHA1 signature method.

Response
oauth_token=7741e9e12cf14f16b8b66064be482a4c&oauth_token_secret=hdhd0244k9j7ao03&oauth_callback_confirmed=true

OAuth authorization API responses are URLEncoded rather than JSON as mandated by the standard.

Authorize request token

Before data endpoints can be accessed, the request token must be authorized for API operations with Inexogy system credentials.

Request
GET /public/v1/oauth1/authorize?oauth_token=7741e9e12cf14f16b8b66064be482a4c&email=example@example.com&password=example
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Response
oauth_verifier=97e1c702e83a4f44a9bfdf7f719f8732

Obtain access token

The client is now ready to request token credentials by making a signed request using all the information from the previous requests.

Request
POST /public/v1/oauth1/access_token
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Authorization: OAuth
      oauth_verifier="97e1c702e83a4f44a9bfdf7f719f8732",
      oauth_nonce="8f9150d1-62f0-4253-a922-bc0ed1268473",
      oauth_signature="8Hq4aI1RNmVQcHTeCi%2Fgp5GyqRM%3D",
      oauth_token="7741e9e12cf14f16b8b66064be482a4c",
      oauth_consumer_key="btgd2cg2bm3lbjqsfv150fj9q8",
      oauth_signature_method="HMAC-SHA1",
      oauth_version="1.0",
      oauth_timestamp="1467792887"
Response
oauth_token=d8e83cf9e2904789ab5e828c66ef4fb9&oauth_token_secret=pfkkdhi9sl3r4s00

Get available meters

Using the token credentials, the client may now access data endpoints such as meters.

Request
GET /public/v1/meters
    Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
    Authorization: OAuth
      oauth_nonce="ca154e4b-c5b6-438e-92ad-2d143591995e",
      oauth_signature="Z2Bn6QkeAqSpWGSHKDaOdLiKwXM%3D",
      oauth_token="d8e83cf9e2904789ab5e828c66ef4fb9",
      oauth_consumer_key="btgd2cg2bm3lbjqsfv150fj9q8",
      oauth_signature_method="HMAC-SHA1",
      oauth_version="1.0",
      oauth_timestamp="1467792887"

The response contains the desired meter objects as documented below.