Skip to main content

Requirements for Integration

Last updated: June 8th, 2023

Maintain a point of contact​

We communicate with our relying parties via the firefox-accounts-notices group. You must subscribe to this list.

Subscribe to and process events​

Mozilla accounts maintains an event broker which is a webhook delivery system to communicate with relying parties. You must register an endpoint to receive events. You will receive events you may or may not care about but some events require you to perform actions:

  • A user opts out of metrics (the metricsEnabled boolean in the profile): When this is false you must not collect any metrics tied to the user. Any existing metrics should be deleted. This boolean should be checked each time a profile is requested.
  • A user deletes their account (event https://schemas.accounts.firefox.com/event/delete-user): The relying party must delete all user records for the deleted user.

Respect API backoff headers​

Please see this section on rate limits.

Practice Good User Data Hygiene​

  1. Accounts should use uid rather than email address as the primary key. An account’s primary email address can change.
  2. Primary email changed notifications should update the contact email stored with the account.
  3. Profile information should not be shared with 3rd parties without explicit consent.
  4. Destroy any outstanding access tokens and refresh tokens whenever a user signals their session or account should be terminated, e.g., the user signs out of your site, closes their account on your site, or unsubscribes from all functionality.

Self Hosted Login Flow​

If you're hosting your own login page you need to send top-of-funnel metrics to FxA:

  1. Initialize top of funnel metrics by calling [/metrics-flow request][metrics-flow-request] with the required query parameters:
    1. entrypoint This is a string identifying the source of the request and should be agreed upon by the Mozilla accounts team.
    2. form_type This is either email (you have an input on your form for an email address) or button (you just have a 'sign in' button)
    3. utm_source
    4. utm_campaign
  2. Propagate the email, flow_id and flow_begin_time query parameters, which are returned from the [/metrics-flow request][metrics-flow-request], in the request to /authentication.

To test without CORS errors your test application must have one of the following URLs: