/auth

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.

Obtain token

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.

SecurityApiKey

Request

Request Body schema: application/json

One of:

rlm required	string The authentication realm as returned in a 401 response.
usr required	string The username to authenticate with.
nnc required	string 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.
cnnc required	string 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.
hash required	string 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)

Responses

200

Authentication response.

400

Bad Request.

post/auth/login

Request samples

Payload
curl
Python
JavaScript
Go

application/json

{"rlm": "eGauge Administration",
"usr": "owner",
"nnc": "eyJ0eXAi...w5GCvM",
"cnnc": "565ce9541eddec103347b5174704e188",
"hash": "ce5e308c27da651964de14f65bd8b059"
}

Response samples

application/json

{"jwt": "eyJ0eXAi...aQvQxY",
"error": "Error message (present if an error occurred)."
}

Revoke token

Revoke the JWT supplied as the bearer token in the Authorization header.

SecurityApiKey

Responses

200

Logout response.

400

Bad Request.

get/auth/logout

Request samples

curl
Python
JavaScript
Go

Response samples

application/json

{"status": "OK",
"error": "Error message (present if an error occurred)."
}

Validate token

This resource returns a 401 response unless the request contains an Authorized header with a valid JWT token. This can be used to check the validity of a JWT token and, if invalid, obtain the realm and server nonce required to refresh the token.

SecurityApiKey

Responses

200

Status response.

401

Unauthorized response.

get/auth/unauthorized

Request samples

curl
Python
JavaScript
Go

Response samples

application/json

{"status": "OK",
"error": "Error message (present if an error occurred)."
}

Get token rights

Return the list of rights associated with the token.

SecurityApiKey

Responses

200

Rights response.

401

Unauthorized response.

get/auth/rights

Request samples

curl
Python
JavaScript
Go

Response samples

application/json

{"usr": "owner",
"rights": ["save",
"ctrl"
]
}

➔ Next to /capture