Services/Sync/Server/API/User/1.0

This wiki page has been integrated in the Mozilla Services doc portal: http://docs.services.mozilla.com/reg/

Weave User API v1.0

Release Date: TBD

All data passed into the User API should be utf-8 encoded.

Terms of Service

By accessing or using the Firefox Sync APIs in connection with the development of your own client software to access the Firefox Sync services (a “Third Party Client”), you acknowledge that you will need to install and use a local version of the Firefox Sync server for multiple account testing and that any use of Mozilla’s hosted Firefox Sync services is subject to Mozilla’s Firefox Sync Terms of Service at https://services.mozilla.com/tos/. Further, you agree (a) to maintain and link to (including on websites from which your Third Party Client may be downloaded) a separate, conspicuous, and reasonably detailed privacy policy detailing how data collected or transmitted by your Third Party Client is managed and protected; (b) that your Third Party Client will only store data in encrypted form on the Firefox Sync servers operated by Mozilla; (c) that you and your Third Party Client will use the Firefox Sync APIs solely for their intended purpose; (d) that your Third Party Client will not hide or mask its identity as it uses the Services and/or Firefox Sync APIs, including by failing to follow required identification conventions; and (e) that you and your Third Party Client will not use the Firefox Sync APIs for any application or service that replicates or attempts to replicate the Services or Firefox Sync experience unless such use is non-confusing (by non-confusing, we mean that people should always know with whom they are dealing and where the information or software they are downloading came from). You may not imply, either directly or by omission, that your Third Party Client is produced or endorsed by Mozilla. By providing access to the Firefox Sync APIs, Mozilla is not granting you a license to any of our trademarks.

URL Semantics

User account URLs follow, for the most part, REST semantics.

The URL for User requests is structured as follows:

https://<server name>/<api pathname>/<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 Weave User API has a set of Weave 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.

https://server/pathname/version/username/node/weave

Returns the Weave Node that the client is located on. Weave-specific calls should be directed to that node. If the value is the string "null", the user hasn't been assigned a node yet (probably due to sign up throttling).

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.

PUT

https://server/pathname/version/username

Requests that an account be created for username.

The JSON payload should include

Field	Description
password	The password to be associated with the account.
email	Email address associated with the account
captcha-challenge	The challenge string from the captcha (see miscellaneous functions below)
captcha-response	The response to the captcha. Only required if WEAVE_REGISTER_USE_CAPTCHA is set

An X-Weave-Secret header 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, or an error message if some portion of the process fails.

POST

https://server/pathname/version/username/email

NOTE: Requires basic authentication with the username and password associated with the account. The auth username must match the username in the path.

Changes the email address associated with the account to the value specified in the POST body.

The server will return the new email address on success, or an error message if some portion of the process fails.

https://server/pathname/version/username/password

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.

Changes the password associated with the account to the value specified in the POST body.

The server will return 'success' on success, or an error message if some portion of the process fails.

DELETE

https://server/pathname/version/username/

NOTE: Requires simple authentication with the username and password associated with the account. The auth username must match the username in the path.

Deletes the user account.

X-Weave-Alert

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.

Miscellaneous Functions

https://server/misc/1.0/captcha_html

Returns an html body string containing a Recaptcha challenge captcha. If the WEAVE_REGISTER_USE_CAPTCHA is set to 1, the PUT API above will expect the challenge and response from this captcha.

Note: this function outputs html, not json.