Table of Contents
  1. JSON
  2. XML
  3. Input Parameters
  4. Response Parameters
  5. Calculating Signature
  6. Login Auditing
  7. Javascript Library

/Account/Login

Allows the client to authenticate itself with the API. This method is an alternative to the QuickLogin and WwwLogin resources that allow the client to login using either Quick-Login or by traditional HTTP means.

If authentication succeeds, a JSON Web Token (or JWT) is returned to the client. This token can be used as a Bearer token in subsequent calls to the API. It needs to be refreshed before it expires.

JSON

Request
{
	"userName":Required(Str(PUserName)),
	"nonce":Required(Str(PNonce)),
	"signature":Required(Str(PSignature)),
	"seconds":Required(Int(0 < PSeconds <= 3600))
}
Response (if successful)
{
	"jwt":Required(Str(PJwt)),
	"expires":Required(DateTime(PExpires))
}

XML

Request
<Login xmlns="https://waher.se/Schema/BrokerAgent.xsd"
       userName=(Required(Str(PUserName)))
       nonce=(Required(Str(PNonce)))
       signature=(Required(Str(PSignature)))
       seconds=(Required(Int(0 < PSeconds <= 3600))) />
Response (if successful)
<LoggedIn xmlns="https://waher.se/Schema/BrokerAgent.xsd"
	jwt=(Required(Str(PJwt)))
	expires=(Required(DateTime(PExpires))) />

Input Parameters

Parameter Description
PUserName User Name of the account to authenticate.
PNonce A unique random string, at least 32 characters long, with sufficient entropy to not be reused again.
PSignature Cryptographic signature of request.
PSeconds Requested number of seconds before the JWT token that will be issued expires.

Response Parameters

Parameter Description
PJwt A token representing the login to the account. This token is seant as a Bearer token in requests requiring authentication.
PExpires When the JWT token expires. The token needs to be renewed before this token expires, if the client wishes to maintain the connection. After the token expires, the client needs to login again.

Calculating Signature

The signature in PSignature is calculated as follows.

  1. Concatenate the strings PUserName ":" Host ":" PNonce and call it s, where Host is the host/domain name of the server. It is taken from the HTTP Host request header, so it must be the same as is used in the URL of the request.

  2. UTF-8 encode the password of the account, and call it Key.

  3. UTF-8 encode the string s, and call it Data.

  4. Calculate the HMAC-SHA256 signature using Key and Data, and call it H.

  5. Base64-encode H. The result is the signature of the request.

Login Auditing

Logins are audited. If too many failed login attempts are received in a row from a given remote endpoint, that endpoint will be temporarily blocked from further attempts. Error message will contain a timestamp when new attempts can be made. If continuing failing, a remote endpoint may become permanently blocked from accessing the API.

Javascript Library

Use the following asynchronous method in the Javascript Library, to call this resource. It computes the signature according to the above specification, and avoids sending password in clear text (albeit over a TLS connection) to the remote endpoint.

var Response = await AgentAPI.Account.Login(UserName,Password,Seconds);

Note: If login to the account is successful, the API library will maintain the resulting token, and make sure to refresh it regularly.

Test




Request Payload:

Response Payload: