As a FxA relier, after a user has logged in to her Firefox account with our OAuth 2.0 API, you can access a collection of APIs attached to the user's account. Many of these APIs are still works in progress.
Current APIs
User profile API
The FxA user profile API provides access to core profile data for the user. Currently, this includes user identifier, email address, and profile image. In the near future, we anticipate this will include locale, screenname, biography, and other data. The scope for the FxA profile API is profile.
Adding new APIs
If you're a Mozilla developer who wants build a new API for FxA or attach an existing API, here's what you need to do:
- Email the FxA team at dev-fxacct@mozilla.org to inform us of your desire to become an attached service.
- Integrate with the FxA OAuth 2.0 infrastructure.
Choose OAuth scopes for your API
OAuth 2.0 has the notion of scopes for OAuth tokens, which indicate the permissions an OAuth token has to access certain data and APIs. You need to decide on what new scopes are appropriate for your service. For example, if you are building a contact syncing solution, an appropriate scope name might be contacts. You might also define sub-scopes, like contacts:read for read-only access to contacts. It is your responsibility to define the OAuth scopes for your API and document them appropriately so developers know how to request tokens with the necessary permissions.
Note: Currently, our OAuth server allows clients to request permission for any scope, although this might be restricted to predefined scopes in the future.
Authenticate your API with FxA OAuth tokens
After a client has acquired an OAuth token with the scopes required to use your API, it will authenticate requests to your API by adding an Authorization HTTP header of the form
Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0Your API will need to extract this token (e.g., in the above example: 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0)and send it to the FxA OAuth verification API. This API takes the OAuth token and returns:
- the FxA uid associated with the token
- the set of scopes granted to the token
You should verify that the scopes required to access your API endpoint is covered by the list of scopes associated the token. You may also limit access based on the FxA user identifier, e.g., only read the contacts associated with that user identifier.