The Firefox Accounts authentication server.
JavaScript Python Other
Latest commit 6e9af38 Aug 24, 2016 @seanmonstar seanmonstar Release v1.68.0
Failed to load latest commit information.
bin fix(geodb): load at startup and log configuration used (#1414) r=vlad… Aug 15, 2016
config refactor(l10n): use fxa-shared locale list (#1411) Aug 16, 2016
docs feat(l10n): localize device list (#1420) r=vbudhram Aug 17, 2016
grunttasks chore(git): Run a quick linting task on pre-push May 27, 2016
lib fix(password): Remove raw token support Aug 24, 2016
scripts fix(e2e-email): fix e2e-email test Aug 1, 2016
test fix(password): Remove raw token support Aug 24, 2016
.dockerignore feat(docker): Add Dockerfile for self-hosting Jan 26, 2016 fix(config): adjust local dev config to support signin confirmation (#… Jun 29, 2016
.eslintrc chore(build): Replacing JSHint with ESLint Jun 19, 2015
.gitignore fix(tests): switch coverage tool, adjust log_tests (#1348) r=vbudhram Jul 18, 2016
.nsprc feat(geolocation): add geolocation data to emails (#1334) Jul 29, 2016
.travis.yml fix(tests): switch coverage tool, adjust log_tests (#1348) r=vbudhram Jul 18, 2016
AUTHORS Add Rishi Baldawa to AUTHORS May 29, 2015 Release v1.68.0 Aug 24, 2016 docs(contributing): Mention git commit guidelines Jan 21, 2016
Gruntfile.js chore(build): Replacing JSHint with ESLint Jun 19, 2015
LICENSE Add a proper copy of the MPL May 16, 2014 chore(tests): allow passing a glob to npm test Jun 30, 2016
Vagrantfile changed vagrant synced_folder to rsync Mar 11, 2014
npm-shrinkwrap.json Release v1.68.0 Aug 24, 2016
package.json Release v1.68.0 Aug 24, 2016

Firefox Accounts Server

Build Status

This project implements the core server-side API for Firefox Accounts. It provides account, device and encryption-key management for the Mozilla Cloud Services ecosystem.


Detailed design document

Detailed API spec

Guidelines for Contributing


  • node 0.10.x or higher
  • npm
  • Grunt


You'll need node 0.10.x or higher and npm to run the server. On some systems running the server as root will cause working directory permissions issues with node. It is recommended that you create a seperate, standard user to ensure a clean and more secure installation.

Clone the git repository and install dependencies:

git clone git://
cd fxa-auth-server
npm install

To start the server in dev memory store mode (ie. NODE_ENV=dev), run:

npm start

This runs a script scripts/ as defined in package.json. This will start up 4 services, three of which listen on the following ports (by default):

  • bin/key_server.js on port 9000
  • test/mail_helper.js on port 9001
  • ./node_modules/fxa-customs-server/bin/customs_server.js on port 7000
  • bin/notifier.js (no port)

When you Ctrl-c your server, all 4 processes will be stopped.

To start the server in dev MySQL store mode (ie. NODE_ENV=dev), run:

npm run start-mysql


Run tests with:

npm test

To select a specific glob of tests to run:

npm test -- test/local/account_routes.js test/local/password_*
  • Note: stop the auth-server before running tests. Otherwise, they will fail with obscure errors.

Reference Client

Dev Deployment

Refer to


Configuration of this project is managed by convict, using the schema in config/index.js.

Default values from this schema can be overridden in two ways:

  1. By setting individual environment variables, as indicated by the env property for each item in the schema.

    For example:

    export CONTENT_SERVER_URL=""
  2. By specifying the path to a conforming JSON file, or a comma-separated list of paths, using the CONFIG_FILES environment variable. Files specified in this way are loaded when the server starts. If the server fails to start, it usually indicates that one of these JSON files does not conform to the schema; check the error message for more information.

    For example:

    export CONFIG_FILES="~/fxa-content-server.json,~/fxa-db.json"


Firefox Accounts authorization is a complicated flow. You can get verbose logging by adjusting the log level in the config.json on your deployed instance. Add a stanza like:

"log": {
  "level": "trace"

Valid level values (from least to most verbose logging) include: "fatal", "error", "warn", "info", "trace", "debug".

Database integration

This server depends on a database server from the fxa-auth-db-mysql repo. When running the tests, it uses a memory-store that mocks behaviour of the production MySQL server.

Using with FxOS

By default, FxOS uses the production Firefox Accounts server ( If you want to use a different account server on a device, you need to update a preference value identity.fxaccounts.auth.uri.

user_pref("identity.fxaccounts.auth.uri", "");
  • ./ push prefs.js


MPL 2.0