Via mod_register_api, it’s possible to both create users and let ’em perform self password resets through through a HTTP API. This allows to rather easily implement external secure web forms for Out-of-Band basic user managing scopes.

The API works in single request-response workflow where the request is a single POST request with a JSON payload and a server response or a http error, below is an example of a proper request:

POST /your_register_base_url HTTP/1.1
Host: yourserveraddress.com:yourchoosenport
Content-Type: application/json

{"username":"usernameofchoice","password":"theuserpassword","ip":"theremoteaddroftheuser","mail":"usermail@usermaildomain.tld",
"auth_token":"yourauthtokenofchoice"}

(The above examples use line breaks for rendering purposes although when sending requests they should be one-line without breaks)

All parameters are necessary, to note, mod_register_json creates and stores a hash of the provided mail address to attempt preventing double registration of multiple accounts and to perform additionaly check on the provided mail address (e.g. to blacklist domains like DEA providers), and also to verify a provided mail address is actually associated to an account for XMPP password resets.

If the request is successful the server will respond with status 200 and a registration token to use to complete it, else it’ll respond with one of the following errors:

• 400 – if there’s an error syntax;
• 401 – whenever an username is already pending registration or the auth token supplied is invalid;
• 403 – whenever registration is forbidden (blacklist, filtered mail etc.);
• 406 – if the username supplied fails nodeprepping or password supplied is too long or short;
• 409 – if the user already exists, or an user is associated already with the supplied e-mail;
• 503 – whenever a request is throttled.

 In case of Password Resets, the above bussness rule apply in which the server, if the request is successful will answer with status 200 and a Password Reset token (to eventually be sent via e-mail to the user) but both the JSON request, and error responses differ.

JSON Array:

{"reset":"emailaddress","ip":"theremoteaddroftheuser","auth_token":"yourauthtokenofchoice"}

Error replies:

• 404 – no user has the provided mail address associated with their account;
• 503 – whenever a request is throttled, as above.

The auth_token element provided in both examples is used as weak mechanism to verify requests and prevent unauthorized use.

As final recommendation, considering the API doesn’t offer a challenge response authentication mechanism it’s STRONGLY ENCOURAGED to always use Secured HTTP when performing API requests to Metronome.