Skip to content

Latest commit

 

History

History
307 lines (214 loc) · 7.04 KB

api.md

File metadata and controls

307 lines (214 loc) · 7.04 KB
Raw

Firefox Accounts Customs Server API

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".

API Endpoints

POST /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).

Parameters

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

Request

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/blockEmail" \
-d '{
  "email": "[email protected]"
}'

Response

Successful requests will produce a "200 OK" response with an empty JSON object as the body.

{}

Failing requests may be due to the following errors:

  • status code 400, code MissingParameters: email is required

POST /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).

Parameters

  • ip - the IP address to ban

Request

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

Response

Successful requests will produce a "200 OK" response with an empty JSON object as the body.

{}

Failing requests may be due to the following errors:

  • status code 400, code MissingParameters: ip is required

POST /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.

Parameters

  • 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

Request

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

Response

Successful requests will produce a "200 OK" response with the blocking advice in the JSON body:

{
  "block": true,
  "retryAfter": 86396
}

block indicates whether or not the action should be blocked and retryAfter tells the client how long it should wait (in seconds) before attempting this action again.

Failing requests may be due to the following errors:

  • status code 400, code MissingParameters: email, ip and action are all required

POST /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.

Parameters

  • ip - the IP address where the request originates
  • action - the name of the action under consideration

Request

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

Response

Successful requests will produce a "200 OK" response with the blocking advice in the JSON body:

{
  "block": true,
  "retryAfter": 86396
}

block indicates whether or not the action should be blocked and retryAfter tells the client how long it should wait (in seconds) before attempting this action again.

Failing requests may be due to the following errors:

  • status code 400, code MissingParameters: ip and action are both required

POST /checkAuthenticated

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

Parameters

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

Request

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

Response

Successful requests will produce a "200 OK" response with the blocking advice in the JSON body:

{
  "block": true,
  "retryAfter": 86396
}

block indicates whether or not the action should be blocked and retryAfter tells the client how long it should wait (in seconds) before attempting this action again.

Failing requests may be due to the following errors:

  • status code 400, code MissingParameters: action, ip and uid are all required

POST /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.

Parameters

  • email - the email address associated with the account
  • ip - the IP address where the request originates

Request

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/failedLoginAttempt" \
-d '{
  "email": "[email protected]",
  "ip": "192.0.2.1"
}'

Response

Successful requests will produce a "200 OK" response:

{}

lockout indicates whether or not the account should be locked out.

Failing requests may be due to the following errors:

  • status code 400, code MissingParameters: email and ip are both required

POST /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).

Parameters

  • email - the email address associated with the account

Request

curl -v \
-H "Content-Type: application/json" \
"http://localhost:7000/passwordReset" \
-d '{
  "email": "[email protected]"
}'

Response

Successful requests will produce a "200 OK" response with an empty JSON object as the body.

{}

Failing requests may be due to the following errors:

  • status code 400, code MissingParameters: email is required