The URL for a Reg request is structured as follows:
https://<server name>/<api path set>/<version>/<username>/<further instruction>
Component | Mozilla Default | Description |
---|---|---|
server name | auth.services.mozilla.com | the hostname of the server |
pathname | user | the prefix associated with the service on the box |
version | 1.0 | The API version. |
username | (none) | the name of the object (user) to be manipulated |
further instruction | (none) | The additional function information as defined in the paths below |
Certain functions use HTTP basic auth (over SSL, so as to maintain password security). If the auth username does not match the username in the path, the server will issue an Error Response.
The Sync User API has a set of Response codes to cover errors in the request or on the server side. The format of a successful response is defined in the appropriate request method section.
GET https://server/pathname/version/username
Returns 1 if the username is in use, 0 if it is available. The answer is in plain text.
Possible errors:
- 503: there was an error getting the information
GET https://server/pathname/version/username/node/weave
Returns the Weave (aka Sync) Node that the client is located on. Sync-specific calls should be directed to that node.
Return value: the node URL, an unadorned (not JSON) string.
node may be ‘null’ if no node can be assigned at this time, probably due to sign up throttling.
Possible errors:
- 503: there was an error getting a node | empty body
- 404: user not found | empty body
GET https://server/pathname/version/username/password_reset
Requests a password reset email be mailed to the email address on file. Returns ‘success’ if an email was successfully sent.
If captchas are enabled for the site, requires captcha-challenge and captcha-response parameters.
Return value:
- “success”
Possible errors:
- 503: problems with looking up the user or sending the email
- 400: 12 (No email address on file)
- 400: 3 (Incorrect or missing username)
- 400: 2 (Incorrect or missing captcha)
PUT https://server/pathname/version/username
Requests that an account be created for username.
The body is a JSON mapping and should include:
- password: the password to be associated with the account.
- e-mail: Email address associated with the account.
- captcha-challenge: The challenge string from the captcha.
- captcha-response: The response to the captcha.
An X-Weave-Secret can be provided containing a secret string known by the server. When provided, it will override the captcha. This is useful for testing and automation.
The server will return the lowercase username on success.
Possible errors:
- 503: there was an error creating the reset code
- 400: 4 (user already exists)
- 400: 6 (Json parse failure)
- 400: 12 (No email address on file)
- 400: 7 (Missing password field)
- 400: 9 (Requested password not strong enough)
- 400: 2 (Incorrect or missing captcha)
POST https://server/pathname/version/username/password
Changes the password associated with the account to the value specified in the POST body.
NOTE: Requires basic authentication with the username and (current) password associated with the account. The auth username must match the username in the path.
Alternately, a valid X-Weave-Password-Reset header can be used, if it contains a code previously obtained from the server.
Return values: “success” on success.
Possible errors:
- 400: 7 (Missing password field)
- 400: 10 (Invalid or missing password reset code)
- 400: 9 (Requested password not strong enough)
- 404: the user does not exists in the database
- 503: there was an error updating the password
- 401: authentication failed
POST https://server/pathname/version/username/email
Changes the email associated with the account to the value specified in the POST body.
NOTE: Requires basic authentication with the username and password associated with the account. The auth username must match the username in the path.
Alternately, a valid X-Weave-Password-Reset header can be used, if it contains a code previously obtained from the server.
Return values: The user email on success.
Possible errors:
- 400: 12 (No email address on file)
- 404: the user does not exists in the database
- 503: there was an error updating the email
- 401: authentication failed
DELETE https://server/pathname/version/username
Deletes the user account.
NOTE: Requires simple authentication with the username and password associated with the account. The auth username must match the username in the path.
Return value:
- 0 on success
Possible errors:
- 503: there was an error removing the user
- 404: the user does not exist in the database
- 401: authentication failed
GET https://server/misc/1.0/captcha_html
Returns an html body string containing a reCaptcha challenge captcha. The PUT API to create a user will expect the challenge and response from this captcha.
Note: this function outputs html, not json.
This header may be sent back from any transaction, and contains potential warning messages, information, or other alerts. The contents are intended to be human-readable.