api-customs.json

{"basePath":"/","info":{"title":"Firefox Accounts Customs Server API Documentation","version":"0.0.1","description":"# Overview\n\n## Request Format\nNone 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.\n\n## Response Format\nAll 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.\n\nFailures 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\".\n\n## API Endpoints\n- [GET /allowedEmailDomains](#operation/getAllowedemaildomains)\n- [GET /allowedIps](#operation/getAllowedips)\n- [GET /allowedPhoneNumbers](#operation/getAllowedphonenumbers)\n- [GET /limits](#operation/getLimits)\n- [GET /](#operation/get)\n- [POST /blockEmail](#operation/postBlockemail)\n- [POST /blockIp](#operation/postBlockip)\n- [POST /check](#operation/postCheck)\n- [POST /checkAuthenticated](#operation/postCheckauthenticated)\n- [POST /checkIpOnly](#operation/postCheckiponly)\n- [POST /failedLoginAttempt](#operation/postFailedloginattempt)\n- [POST /passwordReset](#operation/postPasswordreset)"},"schemes":["https"],"swagger":"2.0","host":"api-documentation.accounts.firefox.com","tags":[],"paths":{"/allowedEmailDomains":{"get":{"summary":"/allowedEmailDomains","operationId":"getAllowedemaildomains","responses":{"default":{"schema":{"type":"string"},"description":"Successful"}}}},"/allowedIPs":{"get":{"summary":"/allowedIps","operationId":"getAllowedips","responses":{"default":{"schema":{"type":"string"},"description":"Successful"}}}},"/allowedPhoneNumbers":{"get":{"summary":"/allowedPhoneNumbers","operationId":"getAllowedphonenumbers","responses":{"default":{"schema":{"type":"string"},"description":"Successful"}}}},"/limits":{"get":{"summary":"/limits","operationId":"getLimits","responses":{"default":{"schema":{"type":"string"},"description":"Successful"}}}},"/":{"get":{"summary":"/","operationId":"get","responses":{"default":{"schema":{"type":"string"},"description":"Successful"}}}},"/blockEmail":{"post":{"summary":"/blockEmail","operationId":"postBlockemail","description":"*Not currently used by anyone.*\n\nUsed by internal services to temporarily ban requests associated with a given email address. These bans last for `config.limits.blockIntervalSeconds` (default: 24 hours).\n\nREQUEST BODY SCHEMA: `application/json`\n- `email`: the email address associated with the account to ban","responses":{"200":{"description":"Successful requests will produce a \"200 OK\" response with an empty JSON object as the body: {}","schema":{"type":"string"}},"400":{"description":"Failing requests may be caused by the following errors:\n- code MissingParameters: email is required"}},"x-codeSamples":[{"lang":"JavaScript","source":"curl -v \\\n-H \"Content-Type: application/json\" \\\n\"http://localhost:7000/blockEmail\" \\\n-d '{\n  \"email\": \"me@example.com\"\n}'"}]}},"/blockIp":{"post":{"summary":"/blockIp","operationId":"postBlockip","description":"*Not currently used by anyone.*\n\nUsed by internal services to temporarily ban requests associated with a given IP address. These bans last for `config.limits.blockIntervalSeconds` (default: 24 hours).\n\nREQUEST BODY SCHEMA: `application/json`\n- `ip`: the IP address to ban","responses":{"200":{"description":"Successful requests will produce a \"200 OK\" response with an empty JSON object as the body: {}","schema":{"type":"string"}},"400":{"description":"Failing requests may be caused by the following errors:\n- code MissingParameters: ip is required"}},"x-codeSamples":[{"lang":"JavaScript","source":"curl -v \\\n-H \"Content-Type: application/json\" \\\n\"http://localhost:7000/blockIp\" \\\n-d '{\n  \"ip\": \"192.0.2.1\"\n}'"}]}},"/check":{"post":{"summary":"/check","operationId":"postCheck","description":"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](https://github.com/mozilla/fxa/blob/main/packages/fxa-customs-server/lib/actions.js).\n\nREQUEST BODY SCHEMA: `application/json`\n- `email`: the email address associated with the account\n- `ip`: the IP address where the request originates\n- `action`: the name of the action under consideration\n- `headers`: the forwarded headers of the original request\n- `payload`: the payload of the original request\n- `phoneNumber`: optional phone number of request","responses":{"200":{"description":"Successful requests will produce a \"200 OK\" response with the blocking advice in the JSON body:\n\n``` js\n    {\n      \"block\": true,\n      \"retryAfter\": 86396\n    }\n```\n\n- `block` indicates whether or not the action should be blocked and `retyAfter` tells the client how long it should wait (in seconds) before attempting this action again.","schema":{"type":"string"}},"400":{"description":"Failing requests may be caused by the following errors:\n- code MissingParameters: email, ip and action are all required"}},"x-codeSamples":[{"lang":"JavaScript","source":"curl -v \\\n-H \"Content-Type: application/json\" \\\n\"http://localhost:7000/check\" \\\n-d '{\n  \"email\": \"me@example.com\",\n  \"ip\": \"192.0.2.1\",\n  \"action\": \"accountCreate\"\n}'"}]}},"/checkAuthenticated":{"post":{"summary":"/checkAuthenticated","operationId":"postCheckauthenticated","description":"Called by the auth server before performing an authenticated action to check whether or not the action should be blocked.\n\nREQUEST BODY SCHEMA: `application/json`\n- `action`: the name of the action under consideration\n- `ip`: the IP address where the request originates\n- `uid`: account identifier","responses":{"200":{"description":"Successful requests will produce a \"200 OK\" response with the blocking advice in the JSON body:\n\n``` js\n    {\n      \"block\": true,\n      \"retryAfter\": 86396\n    }\n```\n\n- `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.","schema":{"type":"string"}},"400":{"description":"Failing requests may be caused by the following errors:\n- code MissingParameters: action, ip and uid are all required"}},"x-codeSamples":[{"lang":"JavaScript","source":"curl -v \\\n-H \"Content-Type: application/json\" \\\n\"http://localhost:7000/checkAuthenticated\" \\\n-d '{\n  \"action\": \"devicesNotify\",\n  \"ip\": \"192.0.2.1\",\n  \"uid\": \"0b65dd742b5a415487f2108cca597044\",\n}'"}]}},"/checkIpOnly":{"post":{"summary":"/checkIpOnly","operationId":"postCheckiponly","description":"Like [/check](#operation/postCheck), 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.\n\nREQUEST BODY SCHEMA: `application/json`\n- `email`: (optional) the email address associated with the account\n- `ip`: the IP address where the request originates\n- `action`: the name of the action under consideration","responses":{"200":{"description":"Successful requests will produce a \"200 OK\" response with the blocking advice in the JSON body:\n\n``` js\n    {\n      \"block\": true,\n      \"retryAfter\": 86396\n    }\n```\n\n- `block` indicates whether or not the action should be blocked and `retyAfter` tells the client how long it should wait (in seconds) before attempting this action again.","schema":{"type":"string"}},"400":{"description":"Failing requests may be caused by the following errors:\n- code MissingParameters: ip and action are both required"}},"x-codeSamples":[{"lang":"JavaScript","source":"curl -v \\\n-H \"Content-Type: application/json\" \\\n\"http://localhost:7000/checkIpOnly\" \\\n-d '{\n  \"ip\": \"192.0.2.1\",\n  \"action\": \"accountCreate\"\n}'"}]}},"/failedLoginAttempt":{"post":{"summary":"/failedLoginAttempt","operationId":"postFailedloginattempt","description":"Called by the auth server to signal to the customs server that a failed login attempt has occured.\n\nThis information is stored by the customs server to enforce some of its policies.\n\nREQUEST BODY SCHEMA: `application/json`\n- `email`: the email address associated with the account\n- `ip`: the IP address where the request originates\n- `action`: (optional) the name of the action under consideration","responses":{"200":{"description":"Successful requests will produce a \"200 OK\" response: {}\n\n- `lockout` indicates whether or not the account should be locked out.","schema":{"type":"string"}},"400":{"description":"Failing requests may be caused by the following errors:\n- code MissingParameters: email and ip are both required"}},"x-codeSamples":[{"lang":"JavaScript","source":"curl -v \\\n-H \"Content-Type: application/json\" \\\n\"http://localhost:7000/failedLoginAttempt\" \\\n-d '{\n  \"email\": \"me@example.com\",\n  \"ip\": \"192.0.2.1\",\n}'"}]}},"/passwordReset":{"post":{"summary":"/passwordReset","operationId":"postPasswordreset","description":"Called by the auth server to signal to the customs server that the password on the account has been successfully reset.\n\nThe customs server uses this information to update its state (expiring bad logins for example).\n\nREQUEST BODY SCHEMA: `application/json`\n- `email`: the email address associated with the account","responses":{"200":{"description":"Successful requests will produce a \"200 OK\" response with an empty JSON object as the body: {}","schema":{"type":"string"}},"400":{"description":"Failing requests may be caused by the following errors:\n- code MissingParameters: email is required"}},"x-codeSamples":[{"lang":"JavaScript","source":"curl -v \\\n-H \"Content-Type: application/json\" \\\n\"http://localhost:7000/passwordReset\" \\\n-d '{\n  \"email\": \"me@example.com\",\n}'"}]}}},"definitions":{}}