fxa-profile-server/docs/API.md

Firefox Accounts Profile Server API

Overview

URL Structure

https://<server-url>/v1/<api-endpoint>

Note that:

• All API access must be over HTTPS
• The URL embeds a version identifier "v1"; future revisions of this API may introduce new version numbers.
• The base URL of the server may be configured on a per-client basis

Authorization

Most endpoints that return user data require authorization from the OAuth server. After a bearer token is received for the user, you can pass it to these endpoints as a header:

Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0

Some endpoints may require certain scopes as well; these will be listed in each endpoint. The general scope profile automatically has all scopes for this server.

Errors

Invalid requests will return 4XX responses. Internal failures will return 5XX. Both will include JSON responses describing the error.

Example error:

{
  "code": 400, // matches the HTTP status code
  "errno": 101, // stable application-level error number
  "error": "Bad Request", // string description of error type
  "message": "Unknown client"
}

The currently-defined error responses are:

• status code, errno: description
• 403, 100: Unauthorized
• 400, 101: Invalid request parameter
• 400, 102: Unsupported image provider
• 400, 125: The request was blocked for security reasons
• 429, 114: Client has sent too many requests
• 500, 103: Image processing error
• 503, 104: OAuth service unavailable
• 503, 105: Auth service unavailable
• 500, 999: internal server error

API Endpoints

• GET /v1/profile
• GET /v1/email
• GET /v1/uid
• GET /v1/avatar
• POST /v1/avatar/upload
• DELETE /v1/avatar/:id
• GET /v1/display_name
• POST /v1/display_name

GET /v1/profile

• scope: profile

Retrieves all properties of a profile that the caller has permission to read.

Request

curl -v \
-H "Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" \
"https://profile.accounts.firefox.com/v1/profile"

Response

{
  "uid": "6d940dd41e636cc156074109b8092f96",
  "email": "user@example.domain",
  "locale": "en-US",
  "amrValues": ["pwd", "otp"],
  "twoFactorAuthentication": true,
  "displayName": "Max Power",
  "avatar": "https://firefoxusercontent.com/a9bff302615cd015692a099f691205cc",
  "avatarDefault": false
}

OpenID Connect UserInfo Endpoint

Per the OpenID Connect Core spec, this endpoint also acts as the "UserInfo" endpoint. Any requests with a token that include the openid scope will include the sub claim, an alias to the uid.

Additional scopes supported for OpenID Connect:

• email

GET /v1/email

• scope: profile:email

Retrieves the user's email address.

Request

curl -v \
-H "Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" \
"https://profile.accounts.firefox.com/v1/email"

Response

{
  "email": "user@example.domain"
}

GET /v1/uid

• scope: profile:uid

Retrieves a consistent, unique ID for this user.

Request

curl -v \
-H "Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" \
"https://profile.accounts.firefox.com/v1/uid"

Response

{
  "uid": "6d940dd41e636cc156074109b8092f96"
}

GET /v1/avatar

• scope: profile:avatar

Returns details of the current user avatar, or an empty object if none.

An avatar id is a 32-length hexstring.

All avatars hosted by Firefox Accounts (see 3rd-party provider docs for their equivalent) can be accessed as multiple sizes. The default size is 200x200 pixels. There is are small (100x100) and large (600x600) variants, which can accessed by adding the _small or _large suffix to the avatar URL.

Request

curl -v \
-H "Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" \
"https://profile.accounts.firefox.com/v1/avatar"

Response

{
  "id": "a9bff302615cd015692a099f691205cc",
  "avatarDefault": false,
  "avatar": "https://firefoxusercontent.com/a9bff302615cd015692a099f691205cc"
}

Response (no avatar set)

{
  "id": "00000000000000000000000000000000",
  "avatarDefault": true,
  "avatar": "https://firefoxusercontent.com/00000000000000000000000000000000"
}

POST /v1/avatar/upload

• scope: profile:avatar:write

Upload image data as an avatar for the user.

Request

The binary data of the image should make up the post body, and the headers Content-Length and Content-Type are required.

curl -v \
-X POST \
-H "Content-Type: image/png" \
-H "Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" \
--data-binary @image.png \
"https://profile.accounts.firefox.com/v1/avatar/upload"

Response

{
  "url": "https://a.p.firefoxusercontent.net/a/81625c14128d46c2b600e74a017fa4a8"
}

DELETE /v1/avatar/:id

• scope: profile:avatar:write

Delete an avatar from the user's profile.

Request

The id of an avatar can be received from GET /v1/avatar.

curl -v \
-X DELETE \
"https://profile.accounts.firefox.com/v1/avatar/81625c14128d46c2b600e74a017fa4a8"

GET /v1/display_name

• scope: profile:display_name

Get the user's display name.

Request

curl -v \
-H "Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" \
"https://profile.accounts.firefox.com/v1/display_name"

Response

{
  "displayName": "Joe Cool"
}

Returns a 204 No Content if the display name is not for the user.

POST /v1/display_name

• scope: profile:display_name:write

Update the user's display name.

Request

• displayName - A new display name

curl -v \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" \
"https://profile.accounts.firefox.com/v1/display_name" \
-d '{
  "displayName": "Snoopy"
}'

Response

{}