eGauge Meter API
License Common Documentation License 1.0
eGauge Meter API
The eGauge WebAPI is a JSON-based API that provides access to eGauge meters. It offers secure means to read device data, configure the device, and perform various control operations.
The WebAPI is intended to eventually replace the eGauge XML API. For new applications, developers are encouraged to use WebAPI rather than the legacy XML API.
The authentication service. Clients can use this to obtain and manage tokens that grant access to the other resources in this API.
The meter uses JSON Web Tokens (JWT or simply token) to restrict access to protected resources. Clients must include such tokens in requests via the HTTP Authorization header. This header must have the form:
Authorization: Bearer JWT
where JWT is a valid token.
Tokens are valid for a limited time; typically for about 10 minutes. However, a meter may revoke a token earlier, e.g., due to a reboot.
There are two ways for supplying credentials to obtain a token:
With a Digest object in the request body, a token is obtained without transmitting the password.
With a Password object in the request body, a token is obtained with a password. This option is available only over a secure connection (https:// scheme).
We recommend using Digest-based authentication whenever possible.
The authentication realm as returned in a 401 response.
The server nonce as returned in a 401 response. Server nonces have a lifetime of about 1 minute. This means a client has to be able to complete the digest login within a minute of receiving a 401 response. If it fails to do so, the server would reject an authentication request, even though the credentials may have been valid. If this were to happen, the client would simply have to redo the digest login with the new nonce. It is therefore advisable for the client to (temporarily) save the password the user entered, so that if the 1 minute lifetime were to expire, the client could reissue the request without having to prompt the user for credentials again.
A client-selected nonce. This should be generated with a cryptographically strong random number generator.
The purpose of the client-nonce is to prevent chosen plain-text attacks by a malicious server (or intermediary). Without the client nonce, a malicious server could try to guess the password by sending specially crafted nonce values. The client nonce prevents such attacks as long as the client uses new and cryptographically strong random value on each login attempt.
The hash which proves that the client possesses the password of the specified username. This must be calculated as the MD5 hash of the string obtained by concatenating ha1, a colon, nnc, a colon, and cnnc. nnc is the server nonce returned in a 401 response, cnnc is the client-selected nonce, and ha1 is the string obtained by calculating the MD5 hash of the string obtained by concatenating the username usr, a colon, realm rlm, a colon, and password pwd. More formally:
ha1 = MD5(usr:rlm:pwd)
hash = MD5(ha1:nnc:cnnc)
curl -i -X POST \ https://webapi.egauge.net/_mock/webapi/4.6/openapi/auth/login \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: application/json' \ -d '{ "rlm": "eGauge Administration", "usr": "owner", "nnc": "eyJ0eXAi...w5GCvM", "cnnc": "565ce9541eddec103347b5174704e188", "hash": "ce5e308c27da651964de14f65bd8b059" }'
{ "jwt": "eyJ0eXAi...aQvQxY", "error": "Error message (present if an error occurred)." }
curl -i -X GET \ https://webapi.egauge.net/_mock/webapi/4.6/openapi/auth/logout \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
{ "status": "OK", "error": "Error message (present if an error occurred)." }
curl -i -X GET \ https://webapi.egauge.net/_mock/webapi/4.6/openapi/auth/rights \ -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Rights response.
The array of rights the user possesses. Possible rights are:
save: The user has the right to change (save) the meter configuration.
ctrl: The user has the right to perform control operations such as putting a device in a particular operational state (e.g., opening or closing a relay or setting the temperature on a thermostat). The device being controlled may be a remote device attached to the meter implementing this API.
{ "usr": "owner", "rights": [ "save", "ctrl" ] }
The service provides the ability to execute various operations for their side effects, such as rebooting the meter. Unless stated otherwise, the resources in this service are available only to users with the save right (see /auth/rights).