Skip to main content
API docs by Redocly

Firefox Accounts Customs Server API Documentation (0.0.1)

Download OpenAPI specification:Download

Overview

Request Format

None of the requests are authenticated. The customs server is an internal service that is running on the same machine as the service that uses it (currently only the auth server) and is listening on localhost.

Response Format

All successful requests will produce a response with HTTP status code of "200" and content-type of "application/json". The structure of the response body will depend on the endpoint in question.

Failures due to invalid behavior from the client will produce a response with HTTP status code of "400" and content-type of "application/json". Failures due to an unexpected situation on the server will produce a response with HTTP status code of "500" and content-type of "application/json".

/allowedEmailDomains

Responses

/allowedIps

Responses

/allowedPhoneNumbers

Responses

/limits

Responses

/

Responses

/blockEmail

Not currently used by anyone.

Used by internal services to temporarily ban requests associated with a given email address. These bans last for config.limits.blockIntervalSeconds (default: 24 hours).

REQUEST BODY SCHEMA: application/json

  • email: the email address associated with the account to ban

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/blockEmail" \
-d '{
  "email": "me@example.com"
}'

/blockIp

Not currently used by anyone.

Used by internal services to temporarily ban requests associated with a given IP address. These bans last for config.limits.blockIntervalSeconds (default: 24 hours).

REQUEST BODY SCHEMA: application/json

  • ip: the IP address to ban

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/blockIp" \
-d '{
  "ip": "192.0.2.1"
}'

/check

Called by the auth server before performing an action on its end to check whether or not the action should be blocked. The endpoint is capable of rate-limiting and blocking requests that involve a variety of actions.

REQUEST BODY SCHEMA: application/json

  • email: the email address associated with the account
  • ip: the IP address where the request originates
  • action: the name of the action under consideration
  • headers: the forwarded headers of the original request
  • payload: the payload of the original request
  • phoneNumber: optional phone number of request

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/check" \
-d '{
  "email": "me@example.com",
  "ip": "192.0.2.1",
  "action": "accountCreate"
}'

/checkAuthenticated

Called by the auth server before performing an authenticated action to check whether or not the action should be blocked.

REQUEST BODY SCHEMA: application/json

  • action: the name of the action under consideration
  • ip: the IP address where the request originates
  • uid: account identifier

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/checkAuthenticated" \
-d '{
  "action": "devicesNotify",
  "ip": "192.0.2.1",
  "uid": "0b65dd742b5a415487f2108cca597044",
}'

/checkIpOnly

Like /check, called by the auth server before performing an action on its end to check whether or not the action should be blocked based only on the request IP.

REQUEST BODY SCHEMA: application/json

  • email: (optional) the email address associated with the account
  • ip: the IP address where the request originates
  • action: the name of the action under consideration

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/checkIpOnly" \
-d '{
  "ip": "192.0.2.1",
  "action": "accountCreate"
}'

/failedLoginAttempt

Called by the auth server to signal to the customs server that a failed login attempt has occured.

This information is stored by the customs server to enforce some of its policies.

REQUEST BODY SCHEMA: application/json

  • email: the email address associated with the account
  • ip: the IP address where the request originates
  • action: (optional) the name of the action under consideration

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/failedLoginAttempt" \
-d '{
  "email": "me@example.com",
  "ip": "192.0.2.1",
}'

/passwordReset

Called by the auth server to signal to the customs server that the password on the account has been successfully reset.

The customs server uses this information to update its state (expiring bad logins for example).

REQUEST BODY SCHEMA: application/json

  • email: the email address associated with the account

Responses

Request samples 

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/passwordReset" \
-d '{
  "email": "me@example.com",
}'