basePath: /v1 info: title: Firefox Accounts API Documentation version: 0.0.1 schemes: - https tags: - name: Auth Server API Overview description: >- This document provides protocol-level details of the Firefox Accounts auth server API. For a prose description of the client/server protocol and details on how each parameter is derived, see the [API design document](https://wiki.mozilla.org/Identity/AttachedServices/KeyServerProtocol). For a reference client implementation, see [fxa-auth-client](https://github.com/mozilla/fxa/tree/main/packages/fxa-auth-client). ## URL Structure for Auth Server All requests use URLs of the form: > `https:///v1/` Note that: - All API access must be over a properly-validated HTTPS connection. - The URL embeds a version identifier `v1`. Future revisions of this API may introduce new version numbers. - The base URI of the server may be configured on a per-client basis: - The canonical URL for Mozilla's hosted Firefox Accounts server is `https://api.accounts.firefox.com/v1`. ## Request Format All POST requests must have a content-type of `application/json` with a UTF8-encoded JSON body and must specify the content-length header. Keys and other binary data are included in the JSON as hexadecimal strings. The following request headers may be specified to influence the behavior of the server: - `Accept-Language` may be used to localize emails and SMS messages. ## Response format All requests receive a JSON response body with a `Content-Type: application/json` header and appropriate `Content-Length` set. The body structure depends on the endpoint returning it. Successful responses will have an HTTP status code of 200 and a `Timestamp` header that contains the current server time in seconds since the epoch. Error responses caused by invalid client behavior will have an HTTP status code in the 4xx range. Error responses caused by server-side problems will have an HTTP status code in the 5xx range. Failures due to invalid behavior from the client. To simplify error handling for the client, the type of error is indicated by both a defined HTTP status code and an application-specific `errno` in the body. For example: ```js { "code": 400, // Matches the HTTP status code "errno": 107, // Stable application-level error number "error": "Bad Request", // String description of the error type "message": "Invalid parameter in request body", // Specific error message "info": "https://docs.dev.lcip.og/errors/1234" // Link to more information } ``` Responses for some errors may include additional parameters. ### Defined errors The currently-defined values for `code` and `errno` are: | status code | errno | description | |-------------|-------|-------------------------------------------------------------------------------| | 400 | 100 | Incorrect Database Patch Level | | 400 | 101 | Account already exists | | 400 | 102 | Unknown account | | 400 | 103 | Incorrect password | | 400 | 104 | Unconfirmed account | | 400 | 105 | Invalid confirmation code | | 400 | 106 | Invalid JSON in request body | | 400 | 107 | Invalid parameter in request body | | 400 | 108 | Missing parameter in request body | | 401 | 109 | Invalid request signature | | 401 | 110 | Invalid authentication token in request signature | | 401 | 111 | Invalid timestamp in request signature | | 411 | 112 | Missing content-length header | | 413 | 113 | Request body too large | | 429 | 114 | Client has sent too many requests | | 401 | 115 | Invalid nonce in request signature | | 410 | 116 | This endpoint is no longer supported | | 400 | 120 | Incorrect email case | | 400 | 123 | Unknown device | | 400 | 124 | Session already registered by another device | | 400 | 125 | The request was blocked for security reasons | | 400 | 126 | Account must be reset | | 400 | 127 | Invalid unblock code | | 400 | 129 | Invalid phone number | | 400 | 130 | Invalid region | | 400 | 131 | Invalid message id | | 500 | 132 | Message rejected | | 400 | 133 | Email account sent complaint | | 400 | 134 | Email account hard bounced | | 400 | 135 | Email account soft bounced | | 400 | 136 | Email already exists | | 400 | 137 | Can not delete primary email | | 400 | 138 | Unverified session | | 400 | 139 | Can not add secondary email that is same as your primary | | 400 | 140 | Email already exists | | 400 | 141 | Email already exists | | 400 | 142 | Sign in with this email type is not currently supported | | 400 | 143 | Unknown email | | 400 | 144 | Email already exists | | 400 | 145 | Reset password with this email type is not currently supported | | 400 | 146 | Invalid signin code | | 400 | 147 | Can not change primary email to an unverified email | | 400 | 148 | Can not change primary email to an email that does not belong to this account | | 400 | 149 | This email can not currently be used to login | | 400 | 150 | Can not resend email code to an email that does not belong to this account | | 500 | 151 | Failed to send email | | 422 | 151 | Failed to send email | | 400 | 152 | Invalid token confirmation code | | 400 | 153 | Expired token confirmation code | | 400 | 154 | TOTP token already exists for this account. | | 400 | 155 | TOTP token not found. | | 400 | 156 | Backup authentication code not found. | | 400 | 157 | Unavailable device command. | | 400 | 158 | Account recovery key not found. | | 400 | 159 | Account recovery key is not valid. | | 400 | 160 | This request requires two step authentication enabled on your account. | | 400 | 161 | Account recovery key already exists. | | 400 | 162 | Unknown client_id | | 400 | 164 | Stale auth timestamp | | 409 | 165 | Redis WATCH detected a conflicting update | | 400 | 166 | Not a public client | | 400 | 167 | Incorrect redirect URI | | 400 | 168 | Invalid response_type | | 400 | 169 | Public clients require PKCE OAuth parameters | | 400 | 170 | Required Authentication Context Reference values could not be satisfied | | 400 | 171 | Incorrect client_secret | | 400 | 172 | Unknown authorization code | | 400 | 173 | Mismatched authorization code | | 400 | 174 | Expired authorization code | | 400 | 175 | Public clients require PKCE OAuth parameters | | 404 | 176 | Unknown customer | | 404 | 177 | Unknown subscription | | 400 | 178 | Unknown subscription plan | | 400 | 179 | Subscription payment token rejected | | 400 | 180 | Subscription has already been cancelled | | 400 | 181 | Customer update rejected | | 400 | 182 | Unknown refresh token | | 400 | 183 | Invalid or expired confirmation code | | 400 | 184 | Subscription has already been cancelled | | 400 | 185 | Subscription plan is not a valid update | | 400 | 186 | Payment method failed | | 409 | 187 | User already subscribed | | 500 | 188 | Failed to find a subscription associated with Stripe source | | 400 | 192 | Billing agreement already on file for this customer | | 400 | 193 | PayPal payment token is missing | | 400 | 194 | PayPal billing agreement is missing for the existing subscriber | | 400 | 195 | Account for this email has an active subscription | | 400 | 196 | Invalid token | | 500 | 197 | IAP Internal Error | | 404 | 198 | Unknown app name | | 400 | 199 | Invalid promotion code | | 503 | 201 | Service unavailable | | 503 | 202 | Feature not enabled | | 500 | 203 | System unavailable, try again soon | | 503 | 204 | This client has been temporarily disabled | | 500 | 205 | Could not login with third party account, please try again later | | 400 | 206 | Can not create password, password already set. | | 400 | 207 | Account creation rejected. | | 403 | 208 | Purchase has been registered to another user. | | 500 | 998 | An internal validation check failed. | The following errors include additional response properties: | errno | description | |-------|-------------------------------------------------------------------------| | 100 | level, levelRequired | | 101 | email | | 102 | email | | 103 | email | | 105 | | | 107 | validation | | 108 | param | | 111 | serverTime | | 114 | retryAfter, retryAfterLocalized, verificationMethod, verificationReason | | 120 | email | | 124 | deviceId | | 125 | verificationMethod, verificationReason | | 126 | email | | 130 | region | | 132 | reason, reasonCode | | 133 | bouncedAt | | 134 | bouncedAt | | 135 | bouncedAt | | 152 | | | 153 | | | 162 | clientId | | 164 | authAt | | 167 | redirectUri | | 169 | invalidScopes | | 171 | foundValue | | 201 | retryAfter | | 202 | retryAfter | | 203 | service, operation | | 998 | op, data | ### Responses from intermediary servers As with any HTTP-based API, clients must handle standard errors that may be returned by proxies, load-balancers or other intermediary servers. These non-application responses can be identified by the absence of a correctly-formatted JSON response body. Common examples include: - `413 Request Entity Too Large`: may be returned by an upstream proxy server. - `502 Gateway Timeout`: may be returned if a load-balancer can't connect to application servers. ## Validation In the documentation that follows, some properties of requests and responses are validated by common code that has been refactored and extracted. For reference, those common validations are defined here. ### lib/routes/validators - `HEX_STRING`: `/^(?:[a-fA-F0-9]{2})+$/` - `BASE_36`: `/^[a-zA-Z0-9]*$/` - `URL_SAFE_BASE_64`: `/^[A-Za-z0-9_-]+$/` - `PKCE_CODE_VERIFIER`: `/^[A-Za-z0-9-\._~]{43,128}$/` - `DISPLAY_SAFE_UNICODE`: `/^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFF])*$/` - `DISPLAY_SAFE_UNICODE_WITH_NON_BMP`: `/^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uE000-\uF8FF\uFFF9-\uFFFF])*$/` - `BEARER_AUTH_REGEX`: `/^Bearer\s+([a-z0-9+\/]+)$/i` - `service`: `string, max(16), regex(/^[a-zA-Z0-9\-]*$/)` - `hexString`: `string, regex(/^(?:[a-fA-F0-9]{2})+$/)` - `clientId`: `module.exports.hexString.length(16)` - `clientSecret`: `module.exports.hexString` - `accessToken`: `module.exports.hexString.length(64)` - `refreshToken`: `module.exports.hexString.length(64)` - `authorizationCode`: `module.exports.hexString.length(64)` - `scope`: `string, max(256), regex(/^[a-zA-Z0-9 _\/.:-]*$/), allow('')` - `assertion`: `string, min(50), max(10240), regex(/^[a-zA-Z0-9_\-\.~=]+$/)` - `pkceCodeChallengeMethod`: `string, valid('S256')` - `pkceCodeChallenge`: `string, length(43), regex(module, exports.URL_SAFE_BASE_64)` - `pkceCodeVerifier`: `string, length(43), regex(module, exports.PKCE_CODE_VERIFIER)` - `jwe`: `string, max(1024), regex(/^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$/)` - `verificationMethod`: `string, valid()` - `authPW`: `string, length(64), regex(HEX_STRING), required` - `wrapKb`: `string, length(64), regex(/^(?:[a-fA-F0-9]{2})+$/)` - `recoveryKeyId`: `string, regex(HEX_STRING), max(32)` - `recoveryData`: `string, regex(/[a-zA-Z0-9.]/), max(1024), required` - `E164_NUMBER`: `/^\+[1-9]\d{1,14}$/` - `DIGITS`: `/^[0-9]+$/` - `DEVICE_COMMAND_NAME`: `/^[a-zA-Z0-9._\/\-:]{1,100}$/` - `IP_ADDRESS`: `string, ip` ### lib/metrics/context - `SCHEMA`: object({ - `deviceId`: string, length(32), regex(HEX_STRING), optional - `entrypoint`: ENTRYPOINT_SCHEMA.optional - `entrypointExperiment`: ENTRYPOINT_SCHEMA.optional - `entrypointVariation`: ENTRYPOINT_SCHEMA.optional - `flowId`: string, length(64), regex(HEX_STRING), optional - `flowBeginTime`: number, integer, positive, optional - `utmCampaign`: UTM_CAMPAIGN_SCHEMA.optional - `utmContent`: UTM_SCHEMA.optional - `utmMedium`: UTM_SCHEMA.optional - `utmSource`: UTM_SCHEMA.optional - `utmTerm`: UTM_SCHEMA.optional }), unknown(false), and('flowId', 'flowBeginTime') - `schema`: SCHEMA.optional - `requiredSchema`: SCHEMA.required ### lib/features - `schema`: array, items(string), optional ### lib/devices - `schema`: { - `id`: isA.string.length(32).regex(HEX_STRING) - `location`: isA.object({ - `city`: isA.string.optional.allow(null) - `country`: isA.string.optional.allow(null) - `state`: isA.string.optional.allow(null) - `stateCode`: isA.string.optional.allow(null) - }) - `name`: isA.string.max(255).regex(DISPLAY_SAFE_UNICODE_WITH_NON_BMP) - `nameResponse`: isA.string.max(255).allow('') - `type`: isA.string.max(16) - `pushCallback`: validators.pushCallbackUrl({ scheme: 'https' }).regex(PUSH_SERVER_REGEX).max(255).allow('') - `pushPublicKey`: isA.string.max(88).regex(URL_SAFE_BASE_64).allow('') - `pushAuthKey`: isA.string.max(24).regex(URL_SAFE_BASE_64).allow('') - `pushEndpointExpired`: isA.boolean.strict - `availableCommands`: isA.object.pattern(validators.DEVICE_COMMAND_NAME - `isA.string.max(2048)) } ## Back-off protocol During periods of heavy load, the server may request that clients enter a "back-off" state, in which they avoid making further requests. At such times, it will return a `503 Service Unavailable` response with a `Retry-After` header denoting the number of seconds to wait before issuing any further requests. It will also include `errno: 201` and a `retryAfter` field matching the value of the `Retry-After` header in the body. For example, the following response indicates that the client should suspend making further requests for 30 seconds: ```js HTTP/1.1 503 Service Unavailable Retry-After: 30 Content-Type: application/json { "code": 503, "errno": 201, "error": "Service Unavailable", "message": "Service unavailable", "info": "https://mozilla.github.io/ecosystem-platform/api#section/Response-format", "retryAfter": 30, "retryAfterLocalized": "in a few seconds" } ``` - name: OAuth Server API Overview description: >- ## URL Structure for OAuth Server > `https:///v1/` Note that: - All API access must be over HTTPS - The URL embeds a version identifier "v1"; future versions of this API may introduce new version numbers. - The base URL of the server may be configured on a per-client basis. ## Errors Invalid requests will return 4XX responses. Internal failures will return 5XX. Both will include JSON responses describing the error. **Example error:** ```js { "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 | |-------------|-------|-------------------------------------------------| | 400 | 101 | unknown client id | | 400 | 102 | incorrect client secret | | 400 | 103 | `redirect_uri` doesn't match registered value | | 401 | 104 | invalid fxa assertion | | 400 | 105 | unknown code | | 400 | 106 | incorrect code | | 400 | 107 | expired code | | 400 | 108 | invalid token | | 400 | 109 | invalid request parameter | | 400 | 110 | invalid response_type | | 401 | 111 | unauthorized | | 403 | 112 | forbidden | | 415 | 113 | invalid content type | | 400 | 114 | invalid scopes | | 400 | 115 | expired token | | 400 | 116 | not a public client | | 400 | 117 | incorrect code_challenge | | 400 | 118 | pkce parameters missing | | 400 | 119 | stale authentication timestamp | | 400 | 120 | mismatch acr value | | 400 | 121 | invalid grant_type | | 500 | 999 | internal server error | ## API Endpoints - [GET /v1/authorization](#tag/OAuth-Server-API-Overview/operation/getAuthorization) - [POST /v1/authorization](#tag/OAuth-Server-API-Overview/operation/postAuthorization) - [POST /v1/authorized-clients](#tag/OAuth-Server-API-Overview/operation/postAuthorizedclients) - [POST /v1/authorized-clients/destroy](#tag/OAuth-Server-API-Overview/operation/postAuthorizedclientsDestroy) - [GET /v1/client/:id](#tag/OAuth-Server-API-Overview/operation/getClientClient_id) - [POST /v1/destroy](#tag/OAuth-Server-API-Overview/operation/postDestroy) - [POST /v1/introspect](#tag/OAuth-Server-API-Overview/operation/postIntrospect) - [GET /v1/jwks](#tag/OAuth-Server-API-Overview/operation/getJwks) - [POST /v1/key-data](#tag/OAuth-Server-API-Overview/operation/postKeydata) - [POST /v1/token](#tag/OAuth-Server-API-Overview/operation/postToken) - [POST /v1/verify](#tag/OAuth-Server-API-Overview/operation/postVerify) x-tagGroups: - name: Firefox Accounts Auth Server API tags: - Auth Server API Overview - Account - Account recovery key - Backup authentication codes - Recovery phone - Devices and Sessions - Emails - Miscellaneous - Oauth - Password - Security events - Session - Sign - Subscriptions - Third Party Authentication - totp - Unblock codes - Util - name: Firefox Accounts OAuth Server API tags: - OAuth Server API Overview swagger: '2.0' host: api.accounts.firefox.com paths: /.well-known/browserid: get: summary: /.well-known/browserid operationId: getWellknownBrowserid description: >- Verifies a user is who they say they are using [BrowserID](https://hacks.mozilla.org/2011/07/introducing-browserid-easier-and-safer-authentication-on-the-web/). It has been deprecated in newer version of Firefox desktop, though some clients still use it. tags: - Miscellaneous responses: default: schema: type: string description: Successful /.well-known/public-keys: get: summary: /.well-known/public-keys operationId: getWellknownPublickeys description: >- Used by clients to generate JSON web tokens, and allows FxA to verify those tokens. tags: - Miscellaneous responses: default: schema: type: string description: Successful /account: get: summary: /account operationId: getAccount description: |- 🔒 Authenticated with session token Returns account data including subscriptions. tags: - Miscellaneous responses: '200': schema: $ref: '#/definitions/Model7' description: Successful /authorization: get: summary: /v1/authorization operationId: getAuthorization description: >- This endpoint starts the OAuth flow. A client redirects the user agent to this url. This endpoint will then redirect to the appropriate content-server page. tags: - OAuth Server API Overview responses: default: schema: type: string description: Successful x-codeSamples: - lang: JavaScript source: >- curl -v "https://oauth.accounts.firefox.com/v1/authorization?client_id=5901bd09376fadaa&state=1234&scope=profile:email&action=signup" post: summary: /v1/authorization operationId: postAuthorization description: >- This endpoint should be used by the fxa-content-server, requesting that we supply a short-lived code (currently 15 minutes) that will be sent back to the client. This code will be traded for a token at the [token][] endpoint. parameters: - in: body name: body schema: $ref: '#/definitions/Model43' tags: - OAuth Server API Overview responses: '200': schema: $ref: '#/definitions/Model44' description: >- A valid request will return a 200 response, with JSON containing the `redirect` to follow.
**Example:** ```js { "redirect": "https://example.domain/path?foo=bar&code=4ab433e31ef3a7cf7c20590f047987922b5c9ceb1faff56f0f8164df053dd94c&state=1234" } ``` **Implicit Grant** \ If requesting an implicit grant (token), the response will match the [/v1/token][token] response. x-codeSamples: - lang: JavaScript source: |- curl -v \ -X POST \ -H "Content-Type: application/json" \ "https://oauth.accounts.firefox.com/v1/authorization" \ -d '{ "client_id": "5901bd09376fadaa", "assertion": "", "state": "1234", "scope": "profile:email" }' /complete_reset_password: get: summary: /complete_reset_password operationId: getComplete_reset_password parameters: - type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ name: email in: query required: true - type: string maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ name: code in: query required: true - type: string maxLength: 64 pattern: ^(?:[a-fA-F0-9]{2})+$ name: token in: query required: true - type: string maxLength: 16 x-format: alphanum: true name: service in: query required: false - type: string maxLength: 2048 name: redirectTo in: query required: false tags: - Util responses: default: schema: type: string description: Successful /jwks: get: summary: /v1/jwks operationId: getJwks description: >- This endpoint returns the [JWKs](https://datatracker.ietf.org/doc/html/rfc7517) that are used for signing OpenID Connect id tokens. tags: - OAuth Server API Overview responses: '200': description: |- A valid response will return JSON of the `keys`.
**Example:** ``` js { "keys": [ "alg": "RS256", "use": "sig", "kty": "RSA", "kid": "2015.12.02-1", "n":"xaQHsKpu1KSK-YEMoLzZS7Xxciy3esGrhrrqW_JBrq3IRmeGLaqlE80zcpIVnStyp9tbet2niYTemt8ug591YWO5Y-S0EgQyFTxnGjzNOvAL6Cd2iGie9QeSehfFLNyRPdQiadYw07fw-h5gweMpVJs8nTgS-Bcorlw9JQM6Il1cUpbP0Lt-F_5qrzlaOiTEAAb4JGOusVh0n-MZfKt7w0mikauMH5KfhflwQDn4YTzRkWJzlldXr1Cs0ZkYzOwS4Hcoku7vd6lqCUO0GgZvkuvCFqdVKzpa4CGboNdfIjcGVF4f1CTQaQ0ao51cwLzq1pgi5aWYhVH7lJcm6O_BQw", "e":"AQAC" ] } ``` schema: type: string x-codeSamples: - lang: JavaScript source: curl -v "http://oauth.accounts.firefox.com/v1/jwks" /recoveryCodes: get: summary: /recoveryCodes operationId: getRecoverycodes description: |- 🔒 Authenticated with session token Return new backup authentication codes while removing old ones. tags: - Backup authentication codes responses: '200': schema: $ref: '#/definitions/Model8' description: Successful post: summary: /recoveryCodes operationId: postRecoverycodes description: |- 🔒 Authenticated with session token Set backup authentication codes (intended for initial set up) parameters: - in: body name: body schema: $ref: '#/definitions/Model8' tags: - Backup authentication codes responses: '200': schema: $ref: '#/definitions/Model57' description: Successful put: summary: /recoveryCodes operationId: putRecoverycodes description: |- 🔒 Authenticated with session token Return new backup authentication codes while removing old ones. parameters: - in: body name: body schema: $ref: '#/definitions/Model8' tags: - Backup authentication codes responses: '200': schema: $ref: '#/definitions/Model210' description: Successful /recovery_emails: get: summary: /recovery_emails operationId: getRecovery_emails description: >- 🔒 Authenticated with session token Returns an array of objects containing details of the email addresses associated with the logged-in user. Currently, the primary email address is always the one from the `accounts` table. tags: - Emails responses: '200': schema: $ref: '#/definitions/Model10' description: Successful /recovery_phone: get: summary: /recovery_phone operationId: getRecovery_phone description: >- 🔒 Authenticated with session token or password forgot token Return whether a recovery phone exists and, if permitted, the masked phone number information. tags: - Recovery phone responses: default: schema: type: string description: Successful delete: summary: /recovery_phone operationId: deleteRecovery_phone description: |- 🔒 Authenticated with verified session token Remove the currently configured recovery phone from the account. tags: - Recovery phone responses: default: schema: type: string description: Successful /securityEvents: get: summary: /securityEvents operationId: getSecurityevents description: >- 🔒 Authenticated with session token Returns a list of all security events for a signed in account having `account.create`, `account.login`, `account.reset` events. tags: - Security events responses: default: schema: type: string description: Successful /verify_email: get: summary: /verify_email operationId: getVerify_email parameters: - type: string maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ name: code in: query required: true - type: string maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ name: uid in: query required: true - type: string maxLength: 16 x-format: alphanum: true name: service in: query required: false - type: string maxLength: 2048 name: redirectTo in: query required: false tags: - Util responses: default: schema: type: string description: Successful /account/attached_clients: get: summary: /account/attached_clients operationId: getAccountAttached_clients description: >- 🔒 Authenticated with session token Returns an array listing all the clients connected to the authenticated user's account, including devices, OAuth clients, and web sessions. This endpoint is primarily designed to power the "devices and apps" view on the user's account settings page. It will only return active sessions. For example, if a user has signed into a service and then later disconnects from that service via account settings connected devices, they would not appear on this list. Depending on the type of client, it will have at least one and possibly several of the following properties: - `clientId`: The OAuth client_id of the connected application. - `sessionTokenId`: The id of the `sessionToken` held by that client, if any. - `refreshTokenId`: The id of the OAuth `refreshToken` held by that client, if any. - `deviceId`: The id of the client's device record, if it has registered one. These identifiers can be passed to [/account/attached_client/destroy](#tag/Devices-and-Sessions/operation/getAccountAttached_clients) in order to disconnect the client. This endpoint returns a maximum 500 last used devices and sessions. parameters: - type: number description: Filter device list to only show devices active since UTC timestamp. name: filterIdleDevicesTimestamp in: query required: false tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model12' description: Successful /account/attached_oauth_clients: get: summary: /account/attached_oauth_clients operationId: getAccountAttached_oauth_clients description: >- 🔒 Authenticated with session token Returns an array listing all the OAuth Clients that the authenticated user has connected to their account. This will only return active sessions. For example, if a user has signed into a service and then later disconnects from that service via account settings connected devices, they would not appear on this list. Each OAuth Client will have exactly one record, and include the 'lastAccessTime' property. tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model14' description: Successful /account/devices: get: summary: /account/devices operationId: getAccountDevices description: >- 🔒 Authenticated with session token or authenticated with OAuth refresh token. Returns an array of registered device objects for the authenticated user. parameters: - type: number description: Filter device list to only show devices active since UTC timestamp. name: filterIdleDevicesTimestamp in: query required: false tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model16' description: Successful /account/keys: get: summary: /account/keys operationId: getAccountKeys description: >- 🔒 Authenticated with key fetch token Get the base-16 bundle of encrypted `kA|wrapKb`. The return value must be decrypted with a key derived from `keyFetchToken`, then `wrapKb` must be further decrypted with a key derived from the user's password. Since `keyFetchToken` is single-use, this can only be done once per session. Note that `keyFetchToken` is consumed regardless of whether the request succeeds or fails. This request will fail unless the account's email address and current session has been verified. tags: - Account responses: '200': schema: $ref: '#/definitions/Model17' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 104` - Unverified account /account/profile: get: summary: /account/profile operationId: getAccountProfile description: >- 🔒 Authenticated with OAuth bearer token or authenticated with session token Get the email and locale of a user. If an OAuth bearer token is used, the values returned depend on the scopes that the token is authorized for: - `email` requires `profile:email` scope. - `locale` requires `profile:locale` scope. - `authenticationMethods` and `authenticatorAssuranceLevel` require `profile:amr` scope. - `accountDisabledAt` requires `profile:account_disabled_at` scope. - `accountLockedAt` requires `profile:account_locked_at` scope. The `profile` scope includes all the above sub-scopes. tags: - Account responses: '200': schema: $ref: '#/definitions/Model18' description: Successful /account/sessions: get: summary: /account/sessions operationId: getAccountSessions description: >- [**DEPRECATED**]: Please use [/account/attached_clients](#tag/Devices-and-Sessions/operation/getAccountAttached_clients) instead. 🔒 Authenticated with session token. Returns an array of session objects for the authenticated user. tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model20' description: Successful deprecated: true /account/status: get: summary: /account/status operationId: getAccountStatus description: |- 🔒🔓 Optionally authenticated with session token Gets the status of an account. parameters: - type: string minLength: 32 maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ name: uid in: query tags: - Account responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 108` - Missing parameter in request body post: summary: /account/status operationId: postAccountStatus description: >- Gets the status of an account without exposing user data through query params. This endpoint is rate limited by [fxa-customs-server](https://github.com/mozilla/fxa/tree/main/packages/fxa-customs-server). parameters: - in: body name: body schema: $ref: '#/definitions/Model80' tags: - Account responses: '200': schema: $ref: '#/definitions/Model81' description: Successful /client/{client_id}: get: summary: /v1/client/{client_id} operationId: getClientClient_id description: >- This endpoint is for the fxa-content-server to retrieve information about a client to show in its user interface. parameters: - type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) asking for permission. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 name: client_id in: path required: true tags: - OAuth Server API Overview responses: '200': schema: $ref: '#/definitions/Model21' description: |- A valid 200 response will be a JSON blob.
**Example:** ``` js { "name": "Where's My Fox", "image_uri": "https://mozilla.org/firefox.png", "redirect_uri": "https://wheres.my.firefox.com/oauth", "trusted": true } ``` x-codeSamples: - lang: JavaScript source: >- curl -v "http://oauth.accounts.firefox.com/v1/client/5901bd09376fadaa" /recoveryKey/{recoveryKeyId}: get: summary: /recoveryKey/{recoveryKeyId} operationId: getRecoverykeyRecoverykeyid description: >- 🔒 Authenticated with account reset token

Retrieve the account recovery data associated with the given account recovery key. parameters: - type: string maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ name: recoveryKeyId in: path required: true tags: - Account recovery key responses: default: schema: type: string description: Successful /recovery_email/status: get: summary: /recovery_email/status operationId: getRecovery_emailStatus description: >- 🔒 Authenticated with session token Returns the 'verified' status for the account's recovery email address. Currently, each account is associated with exactly one email address. This address must be verified before the account can be used (specifically, `GET /account/keys` will return errors until the address is verified). In the future, this may be expanded to include multiple addresses, and/or alternate types of recovery methods (e.g. SMS). A new API will be provided for this extra functionality. This call is used to determine the current state (verified or unverified) of the account. During account creation, until the address is verified, the agent can poll this method to discover when it should proceed with `GET /account/keys`. parameters: - type: string maxLength: 16 name: reason in: query required: false tags: - Emails responses: '200': schema: $ref: '#/definitions/Model22' description: Successful '401': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 110` - Invalid authentication token in request signature /session/status: get: summary: /session/status operationId: getSessionStatus description: >- 🔒 Authenticated with session token Returns a success response if the session token is valid. The response includes detailed information about the session and account state. **Response object:** - `state`: Describes the session's verification state. - `uid`: Account id - `details.accountEmailVerified`: Whether the account's primary email is verified - `details.sessionVerificationMethod`: The verification method used for the session (e.g., 'email-2fa', 'totp-2fa'), or null if not verified - `details.sessionVerified`: Whether the session token itself is verified (no pending token verification) - `details.sessionVerificationMeetsMinimumAAL`: Whether the session's Authentication Assurance Level (AAL) meets or exceeds the account's maximum AAL - `details.verified`: Deprecated! Use accountEmailVerified and sessionVerified instead. tags: - Session responses: '200': schema: $ref: '#/definitions/Model23' description: Successful /totp/exists: get: summary: /totp/exists operationId: getTotpExists description: |- 🔒 Authenticated with session token or password forgot token Checks to see if the user has a TOTP token. tags: - totp responses: '200': schema: $ref: '#/definitions/Model24' description: Successful /account/device/commands: get: summary: /account/device/commands operationId: getAccountDeviceCommands description: >- 🔒 Authenticated with session token or authenticated with OAuth refresh token. Fetches commands enqueued for the current device by prior calls to [/account/devices/invoke_command](#tag/Devices-and-Sessions/operation/postAccountDevicesInvoke_command). The device can page through the enqueued commands by using the `index` and `limit` parameters. For more details, see the [device registration](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/device_registration.md) docs. parameters: - type: number description: >- The index of the most recently seen command item. Only commands enqueued after the given index will be returned. name: index in: query required: false - type: number description: >- The maximum number of commands to return. The default and maximum value for limit is 100. default: 100 minimum: 0 maximum: 100 name: limit in: query required: false tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model26' description: Successful /geo/eligibility/{feature}: get: summary: geo/eligibility/{feature} operationId: getGeoEligibilityFeature description: |- 🔒 Authenticated with session token Returns eligibility for a given feature based on user's country. parameters: - type: string maxLength: 64 name: feature in: path required: true tags: - Miscellaneous responses: '200': schema: $ref: '#/definitions/Model27' description: Successful /oauth/client/{client_id}: get: summary: /oauth/client/{client_id} operationId: getOauthClientClient_id description: >- Retrieve metadata about the specified OAuth client, such as its display name and redirect URI. parameters: - type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) asking for permission. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 name: client_id in: path required: true tags: - Oauth responses: '200': schema: $ref: '#/definitions/Model28' description: Successful /oauth/subscriptions/active: get: summary: /oauth/subscriptions/active operationId: getOauthSubscriptionsActive description: |- 🔒 Authenticated with OAuth bearer token Returns a list of active subscriptions for the user. tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model30' description: Successful /oauth/subscriptions/clients: get: summary: /oauth/subscriptions/clients operationId: getOauthSubscriptionsClients description: >- 🔒 [Authenticated with OAuth bearer token](https://github.com/mozilla/fxa/blob/95cded6e96e2b20f7593153a428d158001bb8d3b/packages/fxa-shared/oauth/constants.ts#L5) Returns a list of clients and their capabilities. tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model32' description: Successful /oauth/subscriptions/plans: get: summary: /oauth/subscriptions/plans operationId: getOauthSubscriptionsPlans description: Returns a list of available subscription plans. tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model35' description: Successful /oauth/subscriptions/productname: get: summary: /oauth/subscriptions/productname operationId: getOauthSubscriptionsProductname description: >- Returns the product name of a valid Stripe `productId` (does not apply to IAP). parameters: - type: string description: >- A unique identifier for the [product](https://stripe.com/docs/api/products/object) purchased. name: productId in: query required: true tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model36' description: Successful /oauth/mozilla-subscriptions/customer/billing-and-subscriptions: get: summary: /oauth/mozilla-subscriptions/customer/billing-and-subscriptions operationId: getOauthMozillasubscriptionsCustomerBillingandsubscriptions description: |- 🔒 Authenticated with OAuth bearer token Returns a customer billing details and subscriptions. tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model38' description: Successful /oauth/subscriptions/invoice/preview-subsequent: get: summary: /oauth/subscriptions/invoice/preview-subsequent operationId: getOauthSubscriptionsInvoicePreviewsubsequent description: >- 🔒 Authenticated with OAuth bearer token Previews a list of subsequent invoices based on existing subscriptions and the customer's `subscriptionId`; includes estimated tax (based on the customer's last known geolocation) and any discount from a promotion code. tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model42' description: Successful /oauth/mozilla-subscriptions/customer/plan-eligibility/{planId}: get: summary: /oauth/mozilla-subscriptions/customer/plan-eligibility/{planid} operationId: getOauthMozillasubscriptionsCustomerPlaneligibilityPlanid description: >- 🔒 Authenticated with OAuth bearer token Get eligibility for a given plan. Returns eligibility as 'create'|'upgrade'|'downgrade'|'blocked_iap'|'invalid'. parameters: - type: string description: >- A unique identifier for the [plan](https://stripe.com/docs/api/plans/object). maxLength: 255 name: planId in: path required: true tags: - Subscriptions responses: default: schema: type: string description: Successful /oauth/subscriptions/iap/plans/{appName}: get: summary: /oauth/subscriptions/iap/plans/{appName} operationId: getOauthSubscriptionsIapPlansAppname description: Returns available plans for In-App Purchase clients. parameters: - type: string name: appName in: path required: true tags: - Subscriptions responses: default: schema: type: string description: Successful /authorized-clients: post: summary: /v1/authorized-clients operationId: postAuthorizedclients description: >- This endpoint returns a list of all OAuth client instances connected to the user's account, including the the scopes granted to each client instance and the time at which it was last active, if available. It must be authenticated with an identity assertion for the user's account. parameters: - in: body name: body schema: $ref: '#/definitions/Model45' tags: - OAuth Server API Overview responses: '200': schema: $ref: '#/definitions/Model48' description: >- A valid 200 response will be a JSON array. For clients that use refresh tokens, each refresh token is taken to represent a separate instance of that client and is returned as a separate entry in the list, with the `refresh_token_id` field distinguishing each. For clients that only use access tokens, all active access tokens are combined into a single entry in the list, and the `refresh_token_id` field will not be present. **Example:** ``` js [ { "client_id": "5901bd09376fadaa", "refresh_token_id": "6e8c38f6a9c27dc0e4df698dc3e3e8b101ad6d79e87842b1ca96ad9b3cd8ed28", "name": "Example Sync Client", "created_time": 1528334748000, "last_access_time": 1528334748000, "scope": ["profile", "https://identity.mozilla.com/apps/oldsync"] }, { "client_id": "5901bd09376fadaa", "refresh_token_id": "eb5e17f246a6b0937356412118ea12b67a638232d6b376e2511cf38a0c4eecf9", "name": "Example Sync Client", "created_time": 1528334748000, "last_access_time": 1528334834000, "scope": ["profile", "https://identity.mozilla.com/apps/oldsync"] }, { "client_id": "23d10a14f474ca41", "name": "Example Website", "created_time": 1328334748000, "last_access_time": 1476677854037, "scope": ["profile:email", "profile:uid"] } ] ``` x-codeSamples: - lang: JavaScript source: |- curl -X POST \ "https://oauth.accounts.firefox.com/v1/authorized-clients" \ -H 'cache-control: no-cache' \ -H "Content-Type: application/json" \ -d '{ "assertion": "eyJhbGciOiJSUzI1NiJ9.eyJwdWJsaWMta2V5Ijp7Imt0eSI6IlJTQSIsIm4iOiJvWmdsNkpwM0Iwcm5BVXppNThrdS1iT0RvR3ZuUGNnWU1UdXQ1WkpyQkJiazBCdWU4VUlRQ0dnYVdrYU5Xb29INkktMUZ6SXU0VFpZYnNqWGJ1c2JRRlQxOGREUkN6VVRubFlXdVZXUzhoSWhKc3lhZHJwSHJOVkI1VndmSlRKZVgwTjFpczBXcU1qdUdOc2VMLXluYnFjOVhueElncFJaai05QnZqY2ZKYXNOUTNZdHR3VHZVaFJOLVFGNWgxQkY1MnA2QmdOTVBvWmQ5MC1EU0xydlpseXp6MEh0Q2tFZnNsc013czVkR0ExTlZ1dEwtcGVDeU50VTFzOEtFaDlzcGxXeF9lQlFybTlYQU1kYXp5ZWR6VUpJU1UyMjZmQzhEUHh5c0ZreXpCbjlDQnFDQUpTNjQzTGFydUVDaS1rMGhKOWFmM2JXTmJnWmpSNVJ2NXF4THciLCJlIjoiQVFBQiJ9LCJwcmluY2lwYWwiOnsiZW1haWwiOiIwNjIxMzM0YzIwNjRjNmYzNmJlOGFkOWE0N2M1NTliY2FwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9LCJpYXQiOjE1MDY5Njk2OTU0MzksImV4cCI6MTUwNjk2OTY5NjQzOSwiZnhhLXZlcmlmaWVkRW1haWwiOiIzMjM2NzJiZUBtb3ppbGxhLmNvbSIsImlzcyI6ImFwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9.hFZd5zFheXOFrXKkJvw6Vpv2l7ctlxuBTvuh5f_jLPAjZoJ9ri-vaJjL_WYBFUvS2xHzfx3-ldxLddyTKwCDAJeB_NkOFL_WJSrMet9C7_Z1hH9HmydeXIT82xJmhrwzW-WOO4ibQvRbocEFiNujynKsg1gS8v0iiYjIX-0cXCrlkxkbVx_8EXJFKDDOGzK9v7Zq6D7gkhP-CHEaNYaTHMn65tLQtBS6snGdaXlxoGHMWmDL6STbnJzWa7sa4QwHf-AgT1rUkQQAUHNa_XLZ0FEzqiCPctMadlihiUZL2V6vxIDBS4mHUF4qj0FvIMJflivDnJVkRNijDuP-h-Lh_A~eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJvYXV0aC5meGEiLCJleHAiOjE1MDY5Njk2OTY0MzksImlzcyI6ImFwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9.M5xyk3RffucgaavjbUm7Eqnt47hzeGbGa2VR3jnVEIlRHfz5S25Qf3ngejwee7XECvIywbaKWeijXFOwS-EkB-7qP1gl4oNJjPmbnCk7S1lgckLWvdMIU-HLGKjrN6Mw76__LzvAbsusSeGmsvTCIVuOJ49Xs3tC1fLyB_re0QNpCcS6AUnJ1KOxIMEM3Om7ysNO5F_AqcD3PwlEti5lbwSk8iP5TWL12C2Nkb_6Hxze_mA1NZNAHOips9bF2J7oy1hqGoMYj1XYZrsyjpPWEuZQATAPlKSjbh1hq-UtDeT7DlwEmIbIUd3JA8qh1MkHKGgavd4fIMap0IPmr9rs4A" }' /destroy: post: summary: /v1/destroy operationId: postDestroy description: >- After a client is done using a token, the responsible thing to do is to destroy the token afterwards. A client can use this route to do so. **Request Parameters** - `token|access_token|refresh_token|refresh_token_id`: The hex string access token. By default, `token` is assumed to be the access token. parameters: - type: string pattern: ^Basic\s+([a-zA-Z0-9+=\/]+)$ name: authorization in: header required: false - in: body name: body schema: $ref: '#/definitions/Model49' tags: - OAuth Server API Overview responses: '200': description: >- A valid request will return an empty response, with a 200 status code. schema: type: string x-codeSamples: - lang: JavaScript source: |- curl -v \ -X POST \ -H "Content-Type: application/json" \ "https://oauth.accounts.firefox.com/v1/destroy" \ -d '{ "token": "558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" }' /get_random_bytes: post: summary: /get_random_bytes operationId: postGet_random_bytes description: >- Get 32 bytes of random data. This should be combined with locally-sourced entropy when creating salts, etc. tags: - Util responses: default: schema: type: string description: Successful /introspect: post: summary: /v1/introspect operationId: postIntrospect description: >- This endpoint returns the status of the token and meta-information about this token. If the token has attribute `active: false`, none of the other attributes in the response will have content parameters: - in: body name: body schema: $ref: '#/definitions/Model50' tags: - OAuth Server API Overview responses: '200': schema: $ref: '#/definitions/Model52' description: |- A valid request will return a JSON response.
**Example:** ``` js { "active": true, "scope": "profile https://identity.mozilla.com/account/subscriptions", "client_id": "59cceb6f8c32317c", "token_type": "access_token", "iat": 1566535888243, "sub": "913fe9395bb946b48c1521d7beb2cb24", "jti": "5ae05d8fe413a749e0f4eb3c495a1c526fb52c85ca5fde516df5dd77d41f7b5b", "exp": 1566537688243 } ``` x-codeSamples: - lang: JavaScript source: |- curl -X POST \ -H "Content-Type: application/json" \ "https://oauth.accounts.firefox.com/v1/introspect" \ -d '{ "token": "558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" }' /key-data: post: summary: /v1/key-data operationId: postKeydata description: This endpoint returns the required scoped key metadata. parameters: - in: body name: body schema: $ref: '#/definitions/Model53' tags: - OAuth Server API Overview responses: '200': schema: type: object properties: string: $ref: '#/definitions/Model54' description: >- A valid response will return JSON the scoped key information for every scope that has scoped keys.
**Example:** ``` js { "https://identity.mozilla.com/apps/sample-scope-can-scope-key": { "identifier": "https://identity.mozilla.com/apps/sample-scope-can-scope-key", "keyRotationSecret": "0000000000000000000000000000000000000000000000000000000000000000", "keyRotationTimestamp": 1506970363512 } } ``` x-codeSamples: - lang: JavaScript source: |- curl -X POST \ "https://oauth.accounts.firefox.com/v1/key-data" \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "client_id": "5901bd09376fadaa", "assertion": "eyJhbGciOiJSUzI1NiJ9.eyJwdWJsaWMta2V5Ijp7Imt0eSI6IlJTQSIsIm4iOiJvWmdsNkpwM0Iwcm5BVXppNThrdS1iT0RvR3ZuUGNnWU1UdXQ1WkpyQkJiazBCdWU4VUlRQ0dnYVdrYU5Xb29INkktMUZ6SXU0VFpZYnNqWGJ1c2JRRlQxOGREUkN6VVRubFlXdVZXUzhoSWhKc3lhZHJwSHJOVkI1VndmSlRKZVgwTjFpczBXcU1qdUdOc2VMLXluYnFjOVhueElncFJaai05QnZqY2ZKYXNOUTNZdHR3VHZVaFJOLVFGNWgxQkY1MnA2QmdOTVBvWmQ5MC1EU0xydlpseXp6MEh0Q2tFZnNsc013czVkR0ExTlZ1dEwtcGVDeU50VTFzOEtFaDlzcGxXeF9lQlFybTlYQU1kYXp5ZWR6VUpJU1UyMjZmQzhEUHh5c0ZreXpCbjlDQnFDQUpTNjQzTGFydUVDaS1rMGhKOWFmM2JXTmJnWmpSNVJ2NXF4THciLCJlIjoiQVFBQiJ9LCJwcmluY2lwYWwiOnsiZW1haWwiOiIwNjIxMzM0YzIwNjRjNmYzNmJlOGFkOWE0N2M1NTliY2FwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9LCJpYXQiOjE1MDY5Njk2OTU0MzksImV4cCI6MTUwNjk2OTY5NjQzOSwiZnhhLXZlcmlmaWVkRW1haWwiOiIzMjM2NzJiZUBtb3ppbGxhLmNvbSIsImlzcyI6ImFwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9.hFZd5zFheXOFrXKkJvw6Vpv2l7ctlxuBTvuh5f_jLPAjZoJ9ri-vaJjL_WYBFUvS2xHzfx3-ldxLddyTKwCDAJeB_NkOFL_WJSrMet9C7_Z1hH9HmydeXIT82xJmhrwzW-WOO4ibQvRbocEFiNujynKsg1gS8v0iiYjIX-0cXCrlkxkbVx_8EXJFKDDOGzK9v7Zq6D7gkhP-CHEaNYaTHMn65tLQtBS6snGdaXlxoGHMWmDL6STbnJzWa7sa4QwHf-AgT1rUkQQAUHNa_XLZ0FEzqiCPctMadlihiUZL2V6vxIDBS4mHUF4qj0FvIMJflivDnJVkRNijDuP-h-Lh_A~eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJvYXV0aC5meGEiLCJleHAiOjE1MDY5Njk2OTY0MzksImlzcyI6ImFwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9.M5xyk3RffucgaavjbUm7Eqnt47hzeGbGa2VR3jnVEIlRHfz5S25Qf3ngejwee7XECvIywbaKWeijXFOwS-EkB-7qP1gl4oNJjPmbnCk7S1lgckLWvdMIU-HLGKjrN6Mw76__LzvAbsusSeGmsvTCIVuOJ49Xs3tC1fLyB_re0QNpCcS6AUnJ1KOxIMEM3Om7ysNO5F_AqcD3PwlEti5lbwSk8iP5TWL12C2Nkb_6Hxze_mA1NZNAHOips9bF2J7oy1hqGoMYj1XYZrsyjpPWEuZQATAPlKSjbh1hq-UtDeT7DlwEmIbIUd3JA8qh1MkHKGgavd4fIMap0IPmr9rs4A", "scope": "https://identity.mozilla.com/apps/sample-scope-can-scope-key" }' /newsletters: post: summary: /newsletters operationId: postNewsletters description: >- 🔒 Authenticated with OAuth bearer token or authenticated with session token parameters: - in: body name: body schema: $ref: '#/definitions/Model56' tags: - Miscellaneous responses: default: schema: type: string description: Successful /recoveryKey: post: summary: /recoveryKey operationId: postRecoverykey description: >- 🔒 Authenticated with session token Creates a new account recovery key for a user. Account recovery keys are one-time-use tokens that can be used to recover the user's kB if they forget their password. For more details, see the [account recovery keys](https://mozilla.github.io/ecosystem-platform/reference/tokens#account-recovery-tokens) docs. parameters: - in: body name: body schema: $ref: '#/definitions/Model58' tags: - Account recovery key responses: default: schema: type: string description: Successful delete: summary: /recoveryKey operationId: deleteRecoverykey description: >- 🔒 Authenticated with session token

This route remove an account's account recovery key. When the key is removed, it can no longer be used to restore an account's kB. tags: - Account recovery key responses: default: schema: type: string description: Successful /token: post: summary: /v1/token operationId: postToken description: >- After receiving an authorization grant from the user, clients exercise that grant at this endpoint to obtain tokens that can be used to access attached services for a particular user. The following types of grant are possible: - `authorization_code`: a single-use code as produced by the [authorization][] endpoint, obtained through a redirect-based authorization flow. - `refresh_token`: a token previously obtained from this endpoint when using access_type=offline. - `fxa-credentials`: an FxA identity assertion, obtained by directly authenticating the user's account. **WARNING**: Do not include `scope` unless you want to downgrade it. parameters: - type: string pattern: ^Basic\s+([a-zA-Z0-9+=\/]+)$ name: authorization in: header required: false - in: body name: body schema: $ref: '#/definitions/Model59' tags: - OAuth Server API Overview responses: '200': schema: $ref: '#/definitions/Model60' description: |- A valid request will return a JSON response.
**Example:** ``` js { "access_token": "558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0", "scope": "profile:email profile:avatar", "token_type": "bearer", "expires_in": 3600, "refresh_token": "58d59cc97c3ca183b3a87a65eec6f93d5be051415b53afbf8491cc4c45dbb0c6", "auth_at": 1422336613 } ``` x-codeSamples: - lang: JavaScript source: |- curl -v \ -X POST \ -H "Content-Type: application/json" \ "https://oauth.accounts.firefox.com/v1/token" \ -d '{ "client_id": "5901bd09376fadaa", "client_secret": "20c6882ef864d75ad1587c38f9d733c80751d2cbc8614e30202dc3d1d25301ff", "ttl": 3600, "grant_type": "authorization_code", "code": "4ab433e31ef3a7cf7c20590f047987922b5c9ceb1faff56f0f8164df053dd94c" }' /verify: post: summary: /v1/verify operationId: postVerify description: >- Attached services can post tokens to this endpoint to learn about which user and scopes are permitted for the token. parameters: - in: body name: body schema: $ref: '#/definitions/Model61' tags: - OAuth Server API Overview responses: '200': schema: $ref: '#/definitions/Model63' description: |- A valid request will return a JSON response. - Note: `email` of the respective user has been **REMOVED**. **Example:** ``` js { "user": "5901bd09376fadaa076afacef5251b6a", "client_id": "45defeda038a1c92", "scope": ["profile:email", "profile:avatar"], } ``` x-codeSamples: - lang: JavaScript source: |- curl -v \ -X POST \ -H "Content-Type: application/json" \ "https://oauth.accounts.firefox.com/v1/verify" \ -d '{ "token": "558f9980ad5a9c279beb52123653967342f702e84d3ab34c7f80427a6a37e2c0" }' /account/create: post: summary: /account/create operationId: postAccountCreate description: >- Creates a user account. The client provides the email address with which this account will be associated and a stretched password. Stretching is detailed on the [onepw](https://mozilla.github.io/ecosystem-platform/explanation/onepw-protocol#client-side-key-stretching) wiki page. This endpoint may send a verification email to the user. Callers may optionally provide the `service` parameter to indicate which service they are acting on behalf of. This is an opaque alphanumeric token that will be embedded in the verification link as a query parameter. Creating an account also logs in. The response contains a `sessionToken` and, optionally, a `keyFetchToken` if the url has a query parameter of `keys=true`. parameters: - type: boolean description: >- Indicates whether a key-fetch token should be returned in the success response. name: keys in: query required: false - type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ name: service in: query - in: body name: body schema: $ref: '#/definitions/Model64' tags: - Account responses: '200': schema: $ref: '#/definitions/Model65' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 101` - Account already exists - `errno: 144` - Email already exists /account/destroy: post: summary: /account/destroy operationId: postAccountDestroy description: >- 🔒🔓 Optionally authenticated with session token Deletes an account. All stored data is erased. The client should seek user confirmation first. The client should erase data stored on any attached services before deleting the user's account data. parameters: - in: body name: body schema: $ref: '#/definitions/Model66' tags: - Account responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 103` - Incorrect password - `errno: 138` - Unverified session /account/device: post: summary: /account/device operationId: postAccountDevice description: >- 🔒 Authenticated with session token or OAuth refresh token Creates or updates the [device registration](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/device_registration.md) record associated with the auth token used for this request. At least one of `name`, `type`, `pushCallback` or the tuple `{ pushCallback, pushPublicKey, pushAuthKey }` must be present. Beware that if you provide `pushCallback` without the pair `{ pushPublicKey, pushAuthKey }`, both of those keys will be reset to the empty string. `pushEndpointExpired` will be reset to false on update if the tuple `{ pushCallback, pushPublicKey, pushAuthKey }` is specified. Devices should register with this endpoint before attempting to access the user's sync data, so that an appropriate device name can be made available to other connected devices. parameters: - in: body name: body schema: $ref: '#/definitions/Model68' tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model69' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 107` - Invalid parameter in request body '503': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 202` - Feature not enabled /account/email_bounce_status: post: summary: /account/email_bounce_status operationId: postAccountEmail_bounce_status description: >- Checks if there are any hard (permanent) email bounces recorded for the provided email address. Used during signup confirmation to detect if verification emails are bouncing. parameters: - in: body name: body schema: $ref: '#/definitions/Model70' tags: - Account responses: '200': schema: $ref: '#/definitions/Model71' description: Successful /account/finish_setup: post: summary: /account/finish_setup operationId: postAccountFinish_setup parameters: - in: body name: body schema: $ref: '#/definitions/Model72' tags: - Account responses: default: schema: type: string description: Successful /account/login: post: summary: /account/login operationId: postAccountLogin description: >- Obtain a `sessionToken` and, optionally, a `keyFetchToken` if `keys=true`. The response includes: - `emailVerified`: Whether the account's primary email address has been verified - `sessionVerified`: Whether the current session token has been verified - `verified`: **Deprecated** - Whether both email and session are verified (equivalent to `emailVerified && sessionVerified`). Use `emailVerified` and `sessionVerified` instead. - `verificationMethod`: Present if verification is incomplete, e.g. `email`, `email-2fa`, `email-otp`, `totp-2fa` - `verificationReason`: Present if verification is incomplete, e.g. `login`, `signup` parameters: - type: boolean description: >- Indicates whether a key-fetch token should be returned in the success response. name: keys in: query required: false - type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ name: service in: query - type: string description: >- If this param is specified, it forces the login to be verified using the specified method. Currently supported methods: - `email`: Sends an email with a confirmation link. - `email-2fa`: Sends an email with a confirmation code. - `email-captcha`: Sends an email with an unblock code. enum: - email - email-otp - email-2fa - email-captcha - totp-2fa name: verificationMethod in: query required: false - in: body name: body schema: $ref: '#/definitions/Model73' tags: - Account responses: '200': schema: $ref: '#/definitions/Model74' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 102` - Unknown account - `errno: 103` - Incorrect password - `errno: 125` - The request was blocked for security reasons - `errno: 127` - Invalid unblock code - `errno: 142` - Sign in with this email type is not currently supported - `errno: 149` - This email can not currently be used to login - `errno: 160` - This request requires two step authentication enabled on your account '422': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 151` - Failed to send email /account/metrics_opt: post: summary: /account/metrics_opt operationId: postAccountMetrics_opt description: >- Set the metrics opt-in or opt-out state for the account. Notifies relying parties of the profile data change. parameters: - in: body name: body schema: $ref: '#/definitions/Model75' tags: - Account responses: default: schema: type: string description: Successful /account/reset: post: summary: /account/reset operationId: postAccountReset description: >- 🔒 Authenticated with account reset token This sets the account password and resets `wrapKb` to a new random value. Account reset tokens are single-use and consumed regardless of whether the request succeeds or fails. They are returned by the `POST /password/forgot/verify_code` endpoint. The caller can optionally request a new `sessionToken` and `keyFetchToken`. parameters: - type: boolean description: >- Indicates whether a new `keyFetchToken` is required, default to `false`. name: keys in: query required: false - in: body name: body schema: $ref: '#/definitions/Model76' tags: - Account responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 108` - Missing parameter in request body /account/scoped-key-data: post: summary: /account/scoped-key-data operationId: postAccountScopedkeydata description: >- 🔒 Authenticated with session token Query for the information required to derive scoped encryption keys requested by the specified OAuth client. parameters: - in: body name: body schema: $ref: '#/definitions/Model77' tags: - Oauth responses: '200': schema: type: object properties: any: $ref: '#/definitions/any' description: Successful /account/set_password: post: summary: /account/set_password operationId: postAccountSet_password description: >- 🔒🔓 Authenticated with oauth access token. Sets the password on an unverified stub account. By default, a verification email will be sent. If the user is subscribed to a product, and we find a valid, matching Stripe productId, they will be added to a list to receive verification reminder emails. parameters: - type: boolean description: Boolean indicating whether a verification email should be sent. default: true name: sendVerifyEmail in: query required: false - in: body name: body schema: $ref: '#/definitions/Model78' tags: - Account responses: '200': schema: $ref: '#/definitions/Model79' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 110` - Invalid token (token already used) /account/stub: post: summary: /account/stub operationId: postAccountStub parameters: - in: body name: body schema: $ref: '#/definitions/Model82' tags: - Account responses: default: schema: type: string description: Successful /authorized-clients/destroy: post: summary: /v1/authorized-clients/destroy operationId: postAuthorizedclientsDestroy description: >- This endpoint revokes tokens granted to a given client. It must be authenticated with an identity assertion for the user's account. parameters: - in: body name: body schema: $ref: '#/definitions/Model83' tags: - OAuth Server API Overview responses: '200': description: A valid 200 response will return an empty JSON object. schema: type: string x-codeSamples: - lang: JavaScript source: |- curl -X POST \ "https://oauth.accounts.firefox.com/v1/authorized-clients/destroy \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -d '{ "client_id": "5901bd09376fadaa", "refresh_token_id": "6e8c38f6a9c27dc0e4df698dc3e3e8b101ad6d79e87842b1ca96ad9b3cd8ed28", "assertion": "eyJhbGciOiJSUzI1NiJ9.eyJwdWJsaWMta2V5Ijp7Imt0eSI6IlJTQSIsIm4iOiJvWmdsNkpwM0Iwcm5BVXppNThrdS1iT0RvR3ZuUGNnWU1UdXQ1WkpyQkJiazBCdWU4VUlRQ0dnYVdrYU5Xb29INkktMUZ6SXU0VFpZYnNqWGJ1c2JRRlQxOGREUkN6VVRubFlXdVZXUzhoSWhKc3lhZHJwSHJOVkI1VndmSlRKZVgwTjFpczBXcU1qdUdOc2VMLXluYnFjOVhueElncFJaai05QnZqY2ZKYXNOUTNZdHR3VHZVaFJOLVFGNWgxQkY1MnA2QmdOTVBvWmQ5MC1EU0xydlpseXp6MEh0Q2tFZnNsc013czVkR0ExTlZ1dEwtcGVDeU50VTFzOEtFaDlzcGxXeF9lQlFybTlYQU1kYXp5ZWR6VUpJU1UyMjZmQzhEUHh5c0ZreXpCbjlDQnFDQUpTNjQzTGFydUVDaS1rMGhKOWFmM2JXTmJnWmpSNVJ2NXF4THciLCJlIjoiQVFBQiJ9LCJwcmluY2lwYWwiOnsiZW1haWwiOiIwNjIxMzM0YzIwNjRjNmYzNmJlOGFkOWE0N2M1NTliY2FwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9LCJpYXQiOjE1MDY5Njk2OTU0MzksImV4cCI6MTUwNjk2OTY5NjQzOSwiZnhhLXZlcmlmaWVkRW1haWwiOiIzMjM2NzJiZUBtb3ppbGxhLmNvbSIsImlzcyI6ImFwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9.hFZd5zFheXOFrXKkJvw6Vpv2l7ctlxuBTvuh5f_jLPAjZoJ9ri-vaJjL_WYBFUvS2xHzfx3-ldxLddyTKwCDAJeB_NkOFL_WJSrMet9C7_Z1hH9HmydeXIT82xJmhrwzW-WOO4ibQvRbocEFiNujynKsg1gS8v0iiYjIX-0cXCrlkxkbVx_8EXJFKDDOGzK9v7Zq6D7gkhP-CHEaNYaTHMn65tLQtBS6snGdaXlxoGHMWmDL6STbnJzWa7sa4QwHf-AgT1rUkQQAUHNa_XLZ0FEzqiCPctMadlihiUZL2V6vxIDBS4mHUF4qj0FvIMJflivDnJVkRNijDuP-h-Lh_A~eyJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJvYXV0aC5meGEiLCJleHAiOjE1MDY5Njk2OTY0MzksImlzcyI6ImFwaS5hY2NvdW50cy5maXJlZm94LmNvbSJ9.M5xyk3RffucgaavjbUm7Eqnt47hzeGbGa2VR3jnVEIlRHfz5S25Qf3ngejwee7XECvIywbaKWeijXFOwS-EkB-7qP1gl4oNJjPmbnCk7S1lgckLWvdMIU-HLGKjrN6Mw76__LzvAbsusSeGmsvTCIVuOJ49Xs3tC1fLyB_re0QNpCcS6AUnJ1KOxIMEM3Om7ysNO5F_AqcD3PwlEti5lbwSk8iP5TWL12C2Nkb_6Hxze_mA1NZNAHOips9bF2J7oy1hqGoMYj1XYZrsyjpPWEuZQATAPlKSjbh1hq-UtDeT7DlwEmIbIUd3JA8qh1MkHKGgavd4fIMap0IPmr9rs4A", }' /linked_account/login: post: summary: /linked_account/login operationId: postLinked_accountLogin parameters: - in: body name: body schema: $ref: '#/definitions/Model84' tags: - Third Party Authentication responses: '200': schema: $ref: '#/definitions/Model85' description: Successful /linked_account/unlink: post: summary: /linked_account/unlink operationId: postLinked_accountUnlink description: 🔒 Authenticated with session token parameters: - in: body name: body schema: $ref: '#/definitions/Model86' tags: - Third Party Authentication responses: '200': schema: $ref: '#/definitions/Model87' description: Successful /mfa/recoveryCodes: post: summary: /mfa/recoveryCodes operationId: postMfaRecoverycodes description: |- 🔒 Authenticated with MFA jwt (scope: mfa:2fa) Set backup authentication codes (intended for initial set up) parameters: - in: body name: body schema: $ref: '#/definitions/Model8' tags: - Backup authentication codes responses: '200': schema: $ref: '#/definitions/Model88' description: Successful put: summary: /mfa/recoveryCodes operationId: putMfaRecoverycodes description: |- 🔒 Authenticated with MFA jwt (scope: mfa:2fa) Return new backup authentication codes while removing old ones. parameters: - in: body name: body schema: $ref: '#/definitions/Model8' tags: - Backup authentication codes responses: '200': schema: $ref: '#/definitions/Model211' description: Successful /mfa/recoveryKey: post: summary: /recoveryKey operationId: postMfaRecoverykey description: >- 🔒 Authenticated with MFA jwt Creates a new account recovery key for a user. Account recovery keys are one-time-use tokens that can be used to recover the user's kB if they forget their password. For more details, see the [account recovery keys](https://mozilla.github.io/ecosystem-platform/reference/tokens#account-recovery-tokens) docs. parameters: - in: body name: body schema: $ref: '#/definitions/Model89' tags: - Account recovery key responses: default: schema: type: string description: Successful delete: summary: /recoveryKey operationId: deleteMfaRecoverykey description: >- 🔒 Authenticated with MFA JWT (scope: mfa:recovery_key)

This route remove an account's account recovery key. When the key is removed, it can no longer be used to restore an account's kB. tags: - Account recovery key responses: default: schema: type: string description: Successful /mfa/recovery_email: post: summary: /recovery_email operationId: postMfaRecovery_email description: >- 🔒 Authenticated with MFA JWT (scope: mfa:email) Add a secondary email address to the logged-in account. The created address will be unverified and will not replace the primary email address. parameters: - in: body name: body schema: $ref: '#/definitions/Model90' tags: - Emails responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 104` - Unverified account - `errno: 138` - Unverified session - `errno: 139` - Can not add secondary email that is same as your primary - `errno: 140` - Email already exists - `errno: 141` - Email already exists /oauth/authorization: post: summary: /oauth/authorization operationId: postOauthAuthorization description: >- 🔒 Authenticated with session token Authorize a new OAuth client connection to the user's account, returning a short-lived authentication code that the client can exchange for access tokens at the OAuth token endpoint. This route behaves like the oauth-server /authorization endpoint except that it is authenticated directly with a sessionToken rather than with a BrowserID assertion. parameters: - in: body name: body schema: $ref: '#/definitions/Model92' tags: - Oauth responses: '200': schema: $ref: '#/definitions/Model93' description: Successful /oauth/destroy: post: summary: /oauth/destroy operationId: postOauthDestroy description: >- Destroy an OAuth access token or refresh token. This is the "token revocation endpoint" as defined in RFC7009 and should be used by clients to explicitly revoke any OAuth tokens that they are no longer using. One of either an authorization header or a client_id is required. parameters: - type: string pattern: ^Basic\s+([a-zA-Z0-9+=\/]+)$ name: authorization in: header required: false - in: body name: body schema: $ref: '#/definitions/Model94' tags: - Oauth responses: '200': description: No information is returned in the response body. schema: type: string '401': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 171` - Incorrect client secret '500': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 162` - Unknown client id. /oauth/id-token-verify: post: summary: /oauth/id-token-verify operationId: postOauthIdtokenverify description: >- Verifies an OIDC ID Token (FxA returns this token at the end of the OAuth flow). The id token contains the user's identification number (uid) plus [other fields](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). parameters: - in: body name: body schema: $ref: '#/definitions/Model95' tags: - Miscellaneous responses: '200': schema: $ref: '#/definitions/Model96' description: Successful /oauth/token: post: summary: /oauth/token operationId: postOauthToken description: >- 🔒🔓 Optionally authenticated with session token Grant new OAuth tokens for use by a connected client, using one of the following grant types: - `grant_type=authorization_code`: A single-use code obtained via OAuth redirect flow. - `grant_type=refresh_token`: A refresh token issued by a previous call to this endpoint. - `grant_type=fxa-credentials`: Directly grant tokens using an FxA sessionToken. This is the "token endpoint" as defined in RFC6749, and behaves like the [oauth-server /token endpoint](#tag/OAuth-Server-API-Overview/operation/postToken) except that the `fxa-credentials` grant can be authenticated directly with a sessionToken rather than with a BrowserID assertion. parameters: - x-alternatives: - $ref: '#/x-alt-definitions/Model1' - $ref: '#/x-alt-definitions/Model3' - $ref: '#/x-alt-definitions/Model5' - $ref: '#/x-alt-definitions/Model7' in: body name: body schema: $ref: '#/definitions/Model98' tags: - Oauth responses: '200': schema: $ref: '#/definitions/Model99' x-alternatives: - $ref: '#/x-alt-definitions/Model8' - $ref: '#/x-alt-definitions/Model10' - $ref: '#/x-alt-definitions/Model12' - $ref: '#/x-alt-definitions/Model14' description: Successful '401': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 110` - Invalid authentication token in request signature '500': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 998` - An internal validation check failed /password/create: post: summary: /password/create operationId: postPasswordCreate description: >- 🔒 Authenticated with session token Creates a new password for the user associated with the session token. Creating a new password will generate new encryption key. parameters: - in: body name: body schema: $ref: '#/definitions/Model100' tags: - Password responses: default: schema: type: string description: Successful /recoveryKey/exists: post: summary: /recoveryKey/exists operationId: postRecoverykeyExists description: >- 🔒🔓 Authenticated with session token or password-forgot token

This route checks to see if given user has setup an account recovery key. When used during the password reset flow, a password-forgot token to check for the status. parameters: - in: body name: body schema: $ref: '#/definitions/Model101' tags: - Account recovery key responses: '200': schema: $ref: '#/definitions/Model102' description: Successful /recoveryKey/hint: post: summary: /recoveryKey/hint operationId: postRecoverykeyHint description: >- 🔒 Authenticated with session token

This route updates the hint associated with a userʼs recovery key. parameters: - in: body name: body schema: $ref: '#/definitions/Model103' tags: - Account recovery key responses: default: schema: type: string description: Successful /recoveryKey/verify: post: summary: /recoveryKey/verify operationId: postRecoverykeyVerify description: 🔒 Authenticated with session token parameters: - in: body name: body schema: $ref: '#/definitions/Model104' tags: - Account recovery key responses: default: schema: type: string description: Successful /recovery_email/resend_code: post: summary: /recovery_email/resend_code operationId: postRecovery_emailResend_code description: >- 🔒 Authenticated with session token Re-sends a verification code to the account's recovery email address. The code is first sent when the account is created, but if the user thinks the message was lost or accidentally deleted, they can request a new message to be sent via this endpoint. The new message will contain the same code as the original message. When this code is provided to `/v1/recovery_email/verify_code`, the email will be marked as 'verified'. This endpoint may send a verification email to the user. Callers may optionally provide the `service` parameter to indicate what identity-attached service they're acting on behalf of. This is an opaque alphanumeric token that will be embedded in the verification link as a query parameter. parameters: - type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ name: service in: query - type: string enum: - upgradeSession maxLength: 32 x-format: alphanum: true name: type in: query required: false - in: body name: body schema: $ref: '#/definitions/Model105' tags: - Emails responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 150` - Can not resend email code to an email that does not belong to this account /recovery_email/verify_code: post: summary: /recovery_email/verify_code operationId: postRecovery_emailVerify_code description: >- Verify tokens and/or recovery emails for an account. If a valid token code is detected, the account email and tokens will be set to verified. If a valid email code is detected, the email will be marked as verified. The verification code will be a random token, delivered in the fragment identifier of a URL sent to the user's email address. Navigating to the URL opens a page that extracts the code from the fragment identifier and performs a POST to `/recovery_email/verify_code`. The link can be clicked from any browser, not just the one being attached to the Firefox account. parameters: - in: body name: body schema: $ref: '#/definitions/Model108' tags: - Emails responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 105` - Invalid verification code /recovery_phone/available: post: summary: /recovery_phone/available operationId: postRecovery_phoneAvailable description: >- 🔒 Authenticated with session token Returns whether the user can set up a recovery phone in their current region and account state. tags: - Recovery phone responses: default: schema: type: string description: Successful /recovery_phone/confirm: post: summary: /recovery_phone/confirm operationId: postRecovery_phoneConfirm description: >- 🔒 Authenticated with verified session token Confirm recovery phone setup by verifying the code sent via SMS and finalize adding the phone number. parameters: - in: body name: body schema: $ref: '#/definitions/Model109' tags: - Recovery phone responses: default: schema: type: string description: Successful /recovery_phone/create: post: summary: /recovery_phone/create operationId: postRecovery_phoneCreate description: >- 🔒 Authenticated with verified session token Start recovery phone setup by validating and sending a verification code to the provided number. parameters: - in: body name: body schema: $ref: '#/definitions/Model110' tags: - Recovery phone responses: default: schema: type: string description: Successful /recovery_phone/message_status: post: summary: /recovery_phone/message_status operationId: postRecovery_phoneMessage_status description: >- Public webhook (Twilio) Accept message status callbacks from Twilio. The request is validated using either an FxA-generated signature or Twilio's signature. tags: - Recovery phone responses: default: schema: type: string description: Successful /session/destroy: post: summary: /session/destroy operationId: postSessionDestroy description: >- 🔒 Authenticated with session token Destroys the current session and invalidates `sessionToken`, to be called when a user signs out. To sign back in, a call must be made to `POST /account/login` to obtain a new `sessionToken`. parameters: - in: body name: body schema: $ref: '#/definitions/Model111' tags: - Session responses: '401': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 110` - Invalid authentication token in request signature /session/duplicate: post: summary: /session/duplicate operationId: postSessionDuplicate description: >- 🔒 Authenticated with session token Create a new `sessionToken` that duplicates the current session. It will have the same verification status as the current session, but will have a distinct verification code. **Response object:** - `uid`: Account id - `sessionToken`: Session Token - `authAt`: Authentication timestamp - `emailVerified`: Whether the account's primary email is verified - `sessionVerified`: Whether the session token itself is verified (no pending token verification) - `verificationMethod`: Present if verification is incomplete, e.g. `email`, `email-2fa`, `email-otp`, `totp-2fa` - `verificationReason`: Present if verification is incomplete, e.g. `login`, `signup` - `verified`: Deprecated! Use emailVerified and sessionVerified instead. parameters: - in: body name: body schema: $ref: '#/definitions/Model112' tags: - Session responses: '200': schema: $ref: '#/definitions/Model113' description: Successful /session/reauth: post: summary: /session/reauth operationId: postSessionReauth description: >- 🔒 Authenticated with session token Re-authenticate an existing session token. This is equivalent to calling `/account/login`, but it re-uses an existing session token rather than generating a new one, allowing the caller to maintain session state such as verification and device registration. The response includes: - `uid`: Account id - `keyFetchToken`: Present if keys were requested. - `verificationMethod`: Present if verification is incomplete, e.g. `email`, `email-2fa`, `email-otp`, `totp-2fa` - `verificationReason`: Present if verification is incomplete, e.g. `login`, `signup` - `emailVerified`: Whether the account's primary email address has been verified - `sessionVerified`: Whether the current session token has been verified - `authAt`: Timestamp of authentication - `metricsEnabled`: Flag indicating if metrics are enabled on the session - `verified`: Deprecated! Use emailVerified and sessionVerified instead. parameters: - type: boolean name: keys in: query required: false - type: string maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ name: service in: query - type: string enum: - email - email-otp - email-2fa - email-captcha - totp-2fa name: verificationMethod in: query required: false - in: body name: body schema: $ref: '#/definitions/Model115' tags: - Session responses: '200': schema: $ref: '#/definitions/Model116' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 102` - Unknown account - `errno: 103` - Incorrect password - `errno: 125` - The request was blocked for security reasons - `errno: 127` - Invalid unblock code - `errno: 142` - Sign in with this email type is not currently supported - `errno: 149` - This email can not currently be used to login - `errno: 160` - This request requires two-step authentication enabled on your account /session/resend_code: post: summary: /session/resend_code operationId: postSessionResend_code description: 🔒 Authenticated with session token tags: - Session responses: default: schema: type: string description: Successful /session/verify_code: post: summary: /session/verify_code operationId: postSessionVerify_code description: 🔒 Authenticated with session token parameters: - in: body name: body schema: $ref: '#/definitions/Model119' tags: - Session responses: default: schema: type: string description: Successful /support/ticket: post: summary: /support/ticket operationId: postSupportTicket description: >- 🔒 Authenticated with support secret or authenticated with OAuth bearer token Creates a support ticket using the Zendesk client. parameters: - in: body name: body schema: $ref: '#/definitions/Model120' tags: - Miscellaneous responses: '200': schema: $ref: '#/definitions/Model121' description: Successful /totp/create: post: summary: /totp/create operationId: postTotpCreate description: >- 🔒 Authenticated with session token Create a new randomly generated TOTP token for a user if they do not currently have one. parameters: - in: body name: body schema: $ref: '#/definitions/Model122' tags: - totp responses: '200': schema: $ref: '#/definitions/Model123' description: Successful /totp/verify: post: summary: /totp/verify operationId: postTotpVerify description: >- 🔒 Authenticated with password forgot token Checks to see if a TOTP code is valid. This is used when a user is resetting their password. parameters: - in: body name: body schema: $ref: '#/definitions/Model124' tags: - totp responses: '200': schema: $ref: '#/definitions/Model125' description: Successful /account/attached_client/destroy: post: summary: /account/attached_client/destroy operationId: postAccountAttached_clientDestroy description: >- 🔒 Authenticated with session token Destroy all tokens held by a connected client, disconnecting it from the user's account. This endpoint is designed to be used in conjunction with [/account/attached_clients](#tag/Devices-and-Sessions/operation/getAccountAttached_clients). It accepts as the request body an object in the same format as returned by that endpoing, and will disconnect that client from the user's account. parameters: - in: body name: body schema: $ref: '#/definitions/Model126' tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model127' description: Successful /account/credentials/status: post: summary: /account/credentials/status operationId: postAccountCredentialsStatus description: >- This provides access to the accounts some info about the format of the account credentials. If the version 2 credential format is in use, the client's unique salt will also be provided. parameters: - in: body name: body schema: $ref: '#/definitions/Model128' tags: - Account responses: '200': schema: $ref: '#/definitions/Model129' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 108` - Missing parameter in request body /account/device/destroy: post: summary: /account/device/destroy operationId: postAccountDeviceDestroy description: >- 🔒 Authenticated with session token or authenticated with OAuth refresh token Destroys a device record and the associated `sessionToken` for the authenticated user. parameters: - in: body name: body schema: $ref: '#/definitions/Model130' tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model131' description: Successful /account/devices/invoke_command: post: summary: /account/devices/invoke_command operationId: postAccountDevicesInvoke_command description: >- 🔒 Authenticated with session token or authenticated with OAuth refresh token. Enqueues a command to be invoked on a target device. For more details, see the [device registration](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/device_registration.md) docs. parameters: - in: body name: body schema: $ref: '#/definitions/Model133' tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model134' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 157` - Unavailable device command /account/devices/notify: post: summary: /account/devices/notify operationId: postAccountDevicesNotify description: >- 🔒 Authenticated with session token or authenticated with OAuth refresh token. Notifies a set of devices associated with the user's account of an event by sending a browser push notification. A typical use case would be to send a notification to another device after sending a tab with Sync, so it can sync too and display the tab in a timely manner. parameters: - x-alternatives: - $ref: '#/x-alt-definitions/Model15' - $ref: '#/x-alt-definitions/Model18' in: body name: body schema: $ref: '#/definitions/Model136' tags: - Devices and Sessions responses: '200': schema: $ref: '#/definitions/Model137' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 107` - Invalid parameter in request body '503': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 202` - Feature not enabled /account/login/reject_unblock_code: post: summary: /account/login/reject_unblock_code operationId: postAccountLoginReject_unblock_code description: >- Used to reject and report unblock codes that were not requested by the user. parameters: - in: body name: body schema: $ref: '#/definitions/Model138' tags: - Unblock codes responses: default: schema: type: string description: Successful /account/login/send_unblock_code: post: summary: /account/login/send_unblock_code operationId: postAccountLoginSend_unblock_code description: Send an unblock code via email to reset rate-limiting for an account. parameters: - in: body name: body schema: $ref: '#/definitions/Model139' tags: - Unblock codes responses: default: schema: type: string description: Successful /account/passwordless/confirm_code: post: summary: /account/passwordless/confirm_code operationId: postAccountPasswordlessConfirm_code description: >- Confirm the OTP code sent via `/account/passwordless/send_code`. On success: - For new users: Creates a new account and returns a session token - For existing users: Returns a session token for the existing account The `isNewAccount` field in the response indicates whether a new account was created. parameters: - in: body name: body schema: $ref: '#/definitions/Model140' tags: - Passwordless responses: '200': schema: $ref: '#/definitions/Model142' description: Successful '400': description: |- Failing requests may be caused by the following errors: - `errno: 183` - Invalid OTP code - `errno: 148` - Account has a password set '429': description: Rate limit exceeded /account/passwordless/resend_code: post: summary: /account/passwordless/resend_code operationId: postAccountPasswordlessResend_code description: |- Resend the OTP code for passwordless authentication. This invalidates any previously sent code and sends a new one. Subject to the same rate limits as `/account/passwordless/send_code`. parameters: - in: body name: body schema: $ref: '#/definitions/Model143' tags: - Passwordless responses: '200': schema: $ref: '#/definitions/Model144' description: Successful '400': description: |- Failing requests may be caused by the following errors: - `errno: 148` - Account has a password set '429': description: Rate limit exceeded /account/passwordless/send_code: post: summary: /account/passwordless/send_code operationId: postAccountPasswordlessSend_code description: >- Send a one-time password (OTP) code to the user's email for passwordless authentication. This endpoint can be used for both: - New user registration (account doesn't exist) - Login for existing passwordless accounts (accounts without a password) Accounts with passwords set cannot use this endpoint. parameters: - in: body name: body schema: $ref: '#/definitions/Model145' tags: - Passwordless responses: '200': schema: $ref: '#/definitions/Model146' description: Successful '400': description: |- Failing requests may be caused by the following errors: - `errno: 148` - Account has a password set, use standard login flow '429': description: Rate limit exceeded /account/unlock/resend_code: post: summary: /account/unlock/resend_code operationId: postAccountUnlockResend_code description: This endpoint is deprecated. tags: - Account responses: '410': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 116` - This endpoint is no longer supported deprecated: true /account/unlock/verify_code: post: summary: /account/unlock/verify_code operationId: postAccountUnlockVerify_code description: This endpoint is deprecated. tags: - Account responses: '410': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 116` - This endpoint is no longer supported deprecated: true /emails/reminders/cad: post: summary: /emails/reminders/cad operationId: postEmailsRemindersCad description: 🔒 Authenticated with session token tags: - Emails responses: default: schema: type: string description: Successful /mfa/password/change: post: summary: /mfa/password/change operationId: postMfaPasswordChange description: >- 🔒 Authenticated with MFA JWT (scope: mfa:password) Perform the "change password" process using JWT authentication. Returns a session token and a key fetch token. parameters: - type: boolean description: >- Indicates whether a new `keyFetchToken` is required, default to `false`. name: keys in: query required: false - in: body name: body schema: $ref: '#/definitions/Model147' tags: - Password responses: default: schema: type: string description: Successful /mfa/password/create: post: summary: /mfa/password/create operationId: postMfaPasswordCreate description: >- 🔒 Authenticated with MFA JWT (scope: mfa:password) Creates a new password for the user associated with the session token. Creating a new password will generate new encryption key. parameters: - in: body name: body schema: $ref: '#/definitions/Model148' tags: - Password responses: default: schema: type: string description: Successful /mfa/recovery_email/destroy: post: summary: /mfa/recovery_email/destroy operationId: postMfaRecovery_emailDestroy description: |- 🔒 Authenticated with session MFA JWT (scope: mfa:email) Delete an email address associated with the logged-in user. parameters: - in: body name: body schema: $ref: '#/definitions/Model149' tags: - Emails responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 138` - Unverified session '401': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 110` - Invalid authentication token in request signature /mfa/recovery_email/set_primary: post: summary: /mfa/recovery_email/set_primary operationId: postMfaRecovery_emailSet_primary description: >- 🔒 Authenticated with session MFA JWT (scope: mfa:email) This endpoint changes a user's primary email address. This email address must belong to the user and be verified. parameters: - in: body name: body schema: $ref: '#/definitions/Model150' tags: - Emails responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 138` - Unverified session - `errno: 147` - Can not change primary email to an unverified email - `errno: 148` - Can not change primary email to an email that does not belong to this account '401': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 110` - Invalid authentication token in request signature /mfa/recovery_phone/change: post: summary: /mfa/recovery_phone/change operationId: postMfaRecovery_phoneChange description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Replace the existing recovery phone with a new one using a valid setup code for the new number. tags: - Recovery phone responses: default: schema: type: string description: Successful /mfa/recovery_phone/confirm: post: summary: /mfa/recovery_phone/confirm operationId: postMfaRecovery_phoneConfirm description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Confirm recovery phone setup (MFA JWT variant) by verifying the code sent via SMS and finalize adding the phone number. parameters: - in: body name: body schema: $ref: '#/definitions/Model151' tags: - Recovery phone responses: default: schema: type: string description: Successful /mfa/recovery_phone/create: post: summary: /mfa/recovery_phone/create operationId: postMfaRecovery_phoneCreate description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Start recovery phone setup (MFA JWT variant) by validating and sending a verification code to the provided number. parameters: - in: body name: body schema: $ref: '#/definitions/Model152' tags: - Recovery phone responses: default: schema: type: string description: Successful /mfa/totp/create: post: summary: /mfa/totp/create operationId: postMfaTotpCreate description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Create a new randomly generated TOTP token for a user if they do not currently have one. This variant requires an MFA JWT and is intended for flows that have already passed MFA requirements. parameters: - in: body name: body schema: $ref: '#/definitions/Model153' tags: - totp responses: '200': schema: $ref: '#/definitions/Model154' description: Successful /mfa/totp/destroy: post: summary: /mfa/totp/destroy operationId: postMfaTotpDestroy description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Deletes the current TOTP token for the user. The underlying session needs to have been verified by TOTP to remove it. It does not bypass that requirement. tags: - totp responses: default: schema: type: string description: Successful /oauth/subscriptions/coupon: post: summary: /oauth/subscriptions/coupon operationId: postOauthSubscriptionsCoupon description: Retrieves coupon details of a valid plan and promotion code. parameters: - in: body name: body schema: $ref: '#/definitions/Model155' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model156' description: Successful /oauth/subscriptions/customer: post: summary: /oauth/subscriptions/customer operationId: postOauthSubscriptionsCustomer description: |- 🔒 Authenticated with OAuth bearer token Create a new customer object for use with subscription payments. parameters: - in: body name: body schema: $ref: '#/definitions/Model157' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model163' description: Successful /oauth/subscriptions/paypal-checkout: post: summary: /oauth/subscriptions/paypal-checkout operationId: postOauthSubscriptionsPaypalcheckout description: >- Retrieves token authorizing transaction to move to the next stage of PayPal checkout. parameters: - in: body name: body schema: $ref: '#/definitions/Model164' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model165' description: Successful /oauth/subscriptions/reactivate: post: summary: /oauth/subscriptions/reactivate operationId: postOauthSubscriptionsReactivate description: >- 🔒 Authenticated with OAuth bearer token Reactivate valid Stripe/PayPal customer subscription (does not apply to IAP). parameters: - in: body name: body schema: $ref: '#/definitions/Model166' tags: - Subscriptions responses: default: schema: type: string description: Successful /password/change/finish: post: summary: /password/change/finish operationId: postPasswordChangeFinish description: >- 🔒 Authenticated with password change token Change the password and update `wrapKb`. Optionally returns `sessionToken` and `keyFetchToken`. parameters: - type: boolean description: >- Indicates whether a new `keyFetchToken` is required, default to `false`. name: keys in: query required: false - in: body name: body schema: $ref: '#/definitions/Model167' tags: - Password responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 138` - Unverified session /password/change/start: post: summary: /password/change/start operationId: postPasswordChangeStart description: >- Begin the "change password" process. Returns a single-use `passwordChangeToken`, to be sent to `POST /password/change/finish`. Also returns a single-use `keyFetchToken`. parameters: - in: body name: body schema: $ref: '#/definitions/Model168' tags: - Password responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 103` - Incorrect password /password/forgot/send_otp: post: summary: /password/forgot/send_otp operationId: postPasswordForgotSend_otp description: >- Requests a One-time Password to be sent to the account's email address(es). The OTP will need to be POSTed to `/password/forgot/verify_otp` to continue the reset password process. parameters: - type: string description: >- Identifies the relying service the user was interacting with that triggered the password reset. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ name: service in: query - type: boolean name: keys in: query required: false - in: body name: body schema: $ref: '#/definitions/Model169' tags: - Password responses: default: schema: type: string description: Successful /password/forgot/verify_code: post: summary: /password/forgot/verify_code operationId: postPasswordForgotVerify_code description: >- 🔒 Authenticated with password forgot token The code returned by `POST /v1/password/forgot/send_code` should be submitted to this endpoint with the `passwordForgotToken`. For successful requests, the server will return `accountResetToken`, to be submitted in requests to `POST /account/reset` to reset the account password and `wrapKb`. parameters: - in: body name: body schema: $ref: '#/definitions/Model170' tags: - Password responses: '200': schema: $ref: '#/definitions/Model171' description: Successful '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 105` - Invalid verification code /password/forgot/verify_otp: post: summary: /password/forgot/verify_otp operationId: postPasswordForgotVerify_otp description: >- Verify the OTP from `/password/forgot/send_otp` to receive the PasswordForgotToken and its code to continue the password reset process. parameters: - in: body name: body schema: $ref: '#/definitions/Model172' tags: - Password responses: default: schema: type: string description: Successful /recovery_phone/reset_password/confirm: post: summary: /recovery_phone/reset_password/confirm operationId: postRecovery_phoneReset_passwordConfirm description: >- 🔒 Authenticated with password forgot token Verify the SMS code sent to the recovery phone to complete password reset verification. tags: - Recovery phone responses: default: schema: type: string description: Successful /recovery_phone/reset_password/send_code: post: summary: /recovery_phone/reset_password/send_code operationId: postRecovery_phoneReset_passwordSend_code description: >- 🔒 Authenticated with password forgot token Send an SMS code to the configured recovery phone to confirm a password reset. tags: - Recovery phone responses: default: schema: type: string description: Successful /recovery_phone/signin/confirm: post: summary: /recovery_phone/signin/confirm operationId: postRecovery_phoneSigninConfirm description: |- 🔒 Authenticated with session token Verify the SMS code sent to the recovery phone to complete sign-in. parameters: - in: body name: body schema: $ref: '#/definitions/Model173' tags: - Recovery phone responses: default: schema: type: string description: Successful /recovery_phone/signin/send_code: post: summary: /recovery_phone/signin/send_code operationId: postRecovery_phoneSigninSend_code description: >- 🔒 Authenticated with session token Send an SMS code to the configured recovery phone to complete sign-in as a 2-step verification method. tags: - Recovery phone responses: default: schema: type: string description: Successful /session/verify/send_push: post: summary: /session/verify/send_push operationId: postSessionVerifySend_push description: >- 🔒 Authenticated with session token Sends a push notification to all push enabled devices to verify current session. tags: - Session responses: default: schema: type: string description: Successful /session/verify/totp: post: summary: /session/verify/totp operationId: postSessionVerifyTotp description: |- 🔒 Authenticated with session token Verifies the current session if the passed TOTP code is valid. parameters: - in: body name: body schema: $ref: '#/definitions/Model174' tags: - totp responses: '200': schema: $ref: '#/definitions/Model175' description: Successful /session/verify/verify_push: post: summary: /session/verify_code operationId: postSessionVerifyVerify_push description: 🔒 Authenticated with session token parameters: - in: body name: body schema: $ref: '#/definitions/Model176' tags: - Session responses: default: schema: type: string description: Successful /totp/setup/complete: post: summary: /totp/setup/complete operationId: postTotpSetupComplete description: >- 🔒 Authenticated with session token Completes TOTP setup by validating the Redis verification flag for the current secret, then persisting the secret to the database as enabled and verified. Cleans up temporary Redis entries. parameters: - in: body name: body schema: $ref: '#/definitions/Model177' tags: - totp responses: '200': schema: $ref: '#/definitions/Model178' description: Successful /totp/setup/verify: post: summary: /totp/setup/verify operationId: postTotpSetupVerify description: >- 🔒 Authenticated with session token Verifies an authenticator app code against the in-progress TOTP secret stored in Redis during setup. On success, marks the setup as verified in Redis and aligns TTLs. parameters: - in: body name: body schema: $ref: '#/definitions/Model179' tags: - totp responses: '200': schema: $ref: '#/definitions/Model180' description: Successful /totp/verify/recoveryCode: post: summary: /totp/verify/recoveryCode operationId: postTotpVerifyRecoverycode description: >- 🔒 Authenticated with password forgot token Checks to see if a Recovery code is valid. If the code is valid, it will be consumed and deleted. This is used when a user is resetting their password. parameters: - in: body name: body schema: $ref: '#/definitions/Model181' tags: - totp responses: '200': schema: $ref: '#/definitions/Model182' description: Successful /mfa/recovery_email/secondary/resend_code: post: summary: /recovery_email/secondary/resend_code operationId: postMfaRecovery_emailSecondaryResend_code description: |- 🔒 Authenticated with session token This endpoint resend the otp verification to verify the secondary email. parameters: - in: body name: body schema: $ref: '#/definitions/Model183' tags: - Emails responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 138` - Unverified session - `errno: 150` - Can not resend email code to an email that does not belong to this account /mfa/recovery_email/secondary/verify_code: post: summary: /recovery_email/secondary/verify_code operationId: postMfaRecovery_emailSecondaryVerify_code description: |- 🔒 Authenticated with session MFA JWT (scope: mfa:email) This endpoint verifies a secondary email using a time based (otp) code. parameters: - in: body name: body schema: $ref: '#/definitions/Model184' tags: - Emails responses: '400': description: >- Failing requests may be caused by the following errors (this is not an exhaustive list): - `errno: 138` - Unverified session - `errno: 105` - Invalid verification code /mfa/totp/replace/confirm: post: summary: /mfa/totp/replace/confirm operationId: postMfaTotpReplaceConfirm description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Verifies the provided code is valid for TOTP and sets the new TOTP token for the user. This is used when a user is replacing their existing TOTP token. parameters: - in: body name: body schema: $ref: '#/definitions/Model185' tags: - totp responses: '200': schema: $ref: '#/definitions/Model186' description: Successful /mfa/totp/replace/start: post: summary: /mfa/totp/replace/start operationId: postMfaTotpReplaceStart description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Create a new randomly generated TOTP token for a user to replace an existing one. An existing TOTP token must exist for the user to request a replacement. parameters: - in: body name: body schema: $ref: '#/definitions/Model187' tags: - totp responses: '200': schema: $ref: '#/definitions/Model188' description: Successful /mfa/totp/setup/complete: post: summary: /mfa/totp/setup/complete operationId: postMfaTotpSetupComplete description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Completes TOTP setup (JWT variant) by validating the Redis verification flag for the current secret, then persisting the secret to the database as enabled and verified. Cleans up temporary Redis entries. parameters: - in: body name: body schema: $ref: '#/definitions/Model189' tags: - totp responses: '200': schema: $ref: '#/definitions/Model190' description: Successful /mfa/totp/setup/verify: post: summary: /mfa/totp/setup/verify operationId: postMfaTotpSetupVerify description: >- 🔒 Authenticated with MFA JWT (scope: mfa:2fa) Verifies an authenticator app code against the in-progress TOTP secret stored in Redis during setup, using an MFA JWT. On success, marks the setup as verified in Redis and aligns TTLs. parameters: - in: body name: body schema: $ref: '#/definitions/Model191' tags: - totp responses: '200': schema: $ref: '#/definitions/Model192' description: Successful /oauth/subscriptions/active/new: post: summary: /oauth/subscriptions/active/new operationId: postOauthSubscriptionsActiveNew description: |- 🔒 Authenticated with OAuth bearer token Subscribe the user to a price using a payment method id. parameters: - in: body name: body schema: $ref: '#/definitions/Model193' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model194' description: Successful /oauth/subscriptions/active/new-paypal: post: summary: /oauth/subscriptions/active/new-paypal operationId: postOauthSubscriptionsActiveNewpaypal description: Create subscription for the provided customer using PayPal. parameters: - in: body name: body schema: $ref: '#/definitions/Model195' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model196' description: Successful /oauth/subscriptions/iap/app-store-notification: post: summary: /oauth/subscriptions/iap/app-store-notification operationId: postOauthSubscriptionsIapAppstorenotification description: |- 🔒 payload validated against Apple certificates Update stored purchase information with latest subscription status. parameters: - in: body name: body schema: $ref: '#/definitions/Model197' tags: - Subscriptions responses: default: schema: type: string description: Successful /oauth/subscriptions/iap/rtdn: post: summary: /oauth/subscriptions/iap/rtdn operationId: postOauthSubscriptionsIapRtdn description: Handles a Google Play Real-time Developer Notification. parameters: - in: body name: body schema: $ref: '#/definitions/Model198' tags: - Subscriptions responses: default: schema: type: string description: Successful /oauth/subscriptions/invoice/preview: post: summary: /oauth/subscriptions/invoice/preview operationId: postOauthSubscriptionsInvoicePreview description: >- Previews an invoice for a new plan where the user is not yet subscribed (and therefore there is no `subscriptionId`); includes estimated tax (based on the user's geolocation) and any discount from a promotion code. parameters: - in: body name: body schema: $ref: '#/definitions/Model199' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model200' description: Successful /oauth/subscriptions/invoice/retry: post: summary: oauth/subscriptions/invoice/retry operationId: postOauthSubscriptionsInvoiceRetry description: |- 🔒 Authenticated with OAuth bearer token Retry an incomplete subscription invoice with a new payment method id. parameters: - in: body name: body schema: $ref: '#/definitions/Model201' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model202' description: Successful /oauth/subscriptions/paymentmethod/billing-agreement: post: summary: /oauth/subscriptions/paymentmethod/billing-agreement operationId: postOauthSubscriptionsPaymentmethodBillingagreement description: |- 🔒 Authenticated with OAuth bearer token Updates the billing agreement for a user with a new PayPal token. parameters: - in: body name: body schema: $ref: '#/definitions/Model203' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model163' description: Successful /oauth/subscriptions/paymentmethod/default: post: summary: /oauth/subscriptions/paymentmethod/default operationId: postOauthSubscriptionsPaymentmethodDefault description: >- 🔒 Authenticated with OAuth bearer token Update a user's default payment method for invoices to the attached payment method id. parameters: - in: body name: body schema: $ref: '#/definitions/Model204' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model163' description: Successful /oauth/subscriptions/setupintent/create: post: summary: /oauth/subscriptions/setupintent/create operationId: postOauthSubscriptionsSetupintentCreate description: >- 🔒 Authenticated with OAuth bearer token Create a new setup intent for attaching a new payment method to the user. tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model205' description: Successful /oauth/subscriptions/stripe/event: post: summary: /oauth/subscriptions/stripe/event operationId: postOauthSubscriptionsStripeEvent description: >- Handles webhook events from Stripe by pre-processing the incoming event and dispatching to the appropriate sub-handler. parameters: - type: string name: stripe-signature in: header required: true tags: - Subscriptions responses: default: schema: type: string description: Successful /oauth/subscriptions/iap/app-store-transaction/{appName}: post: summary: /oauth/subscriptions/iap/app-store-transaction/{appName} operationId: postOauthSubscriptionsIapAppstoretransactionAppname description: >- 🔒 authenticated with OAuth bearer token Validate and store an App Store Original Transaction ID for the given user. Returns token validity. parameters: - type: string name: appName in: path required: true - in: body name: body schema: $ref: '#/definitions/Model206' tags: - Subscriptions responses: default: schema: type: string description: Successful /oauth/subscriptions/iap/play-token/{appName}: post: summary: /oauth/subscriptions/iap/play-token/{appName} operationId: postOauthSubscriptionsIapPlaytokenAppname description: >- 🔒 Authenticated with OAuth bearer token Validate and store a Play Store Puchase Token for the given user. Returns token validity. parameters: - type: string name: appName in: path required: true - in: body name: body schema: $ref: '#/definitions/Model207' tags: - Subscriptions responses: default: schema: type: string description: Successful /oauth/subscriptions/paymentmethod/failed/detach: post: summary: /oauth/subscriptions/paymentmethod/failed/detach operationId: postOauthSubscriptionsPaymentmethodFailedDetach description: >- 🔒 Authenticated with OAuth bearer token Detaches a payment method from a Stripe customer without any subscriptions. This is only for Stripe customers; excludes customers using PayPal, Apple, Google, etc). parameters: - in: body name: body schema: $ref: '#/definitions/Model208' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model209' description: Successful /oauth/subscriptions/active/{subscriptionId}: put: summary: /oauth/subscriptions/active/{subscriptionId} operationId: putOauthSubscriptionsActiveSubscriptionid description: >- 🔒 Authenticated with OAuth bearer token Updates an active subscription for Stripe customer based on their Stripe `subscriptionId` (does not apply to IAP). parameters: - type: string description: >- A unique identifier for the Stripe [subscription](https://stripe.com/docs/api/subscriptions/object). maxLength: 255 name: subscriptionId in: path required: true - in: body name: body schema: $ref: '#/definitions/Model212' tags: - Subscriptions responses: '200': schema: $ref: '#/definitions/Model213' description: Successful delete: summary: /oauth/subscriptions/active/{subscriptionid} operationId: deleteOauthSubscriptionsActiveSubscriptionid description: |- 🔒 Authenticated with OAuth bearer token Cancel an active subscription for the user. parameters: - type: string description: >- A unique identifier for the Stripe [subscription](https://stripe.com/docs/api/subscriptions/object). maxLength: 255 name: subscriptionId in: path required: true tags: - Subscriptions responses: default: schema: type: string description: Successful /oauth/subscriptions/coupon/apply: put: summary: /oauth/subscriptions/coupon/apply operationId: putOauthSubscriptionsCouponApply description: >- Applies an existing, valid promotion code to an active customer subscription. Note: - The coupon can only be applied to the upcoming invoice, as current invoices are finalized and cannot be editable - This endpoint checks that the customer ID associated with the subscription ID matches the Stripe customer ID of the FxA user - The promotion code needs to be included within the metadata of either the product or specific plan parameters: - in: body name: body schema: $ref: '#/definitions/Model214' tags: - Subscriptions responses: default: schema: type: string description: Successful definitions: Model1: type: object properties: email: type: string isPrimary: type: boolean verified: type: boolean required: - email - isPrimary - verified emails: type: array items: $ref: '#/definitions/Model1' Model2: type: object properties: providerId: type: number authAt: type: number enabled: type: boolean required: - providerId - authAt - enabled linkedAccounts: type: array items: $ref: '#/definitions/Model2' totp: type: object properties: exists: type: boolean verified: type: boolean required: - exists - verified backupCodes: type: object properties: hasBackupCodes: type: boolean count: type: number required: - hasBackupCodes - count recoveryKey: type: object properties: exists: type: boolean estimatedSyncDeviceCount: type: number required: - exists recoveryPhone: type: object properties: exists: type: boolean phoneNumber: type: string nationalFormat: type: string available: type: boolean required: - exists - available Model3: type: object properties: name: type: string createdAt: type: number verified: type: boolean required: - name - createdAt - verified securityEvents: type: array items: $ref: '#/definitions/Model3' _subscription_type: type: string enum: - web period: type: object properties: end: type: number start: type: number required: - end - start Model4: type: object properties: amount: type: number currency: type: string id: type: string name: type: string period: $ref: '#/definitions/period' required: - amount - currency - id - name - period line_items: type: array items: $ref: '#/definitions/Model4' Model5: type: object properties: amount: type: number inclusive: type: boolean display_name: type: string required: - amount - inclusive tax: type: array items: $ref: '#/definitions/Model5' discount: type: object properties: amount: type: number amount_off: type: number percent_off: type: number required: - amount - amount_off - percent_off latest_invoice_items: type: object properties: line_items: $ref: '#/definitions/line_items' subtotal: type: number subtotal_excluding_tax: type: number total: type: number total_excluding_tax: type: number tax: $ref: '#/definitions/tax' discount: $ref: '#/definitions/discount' one_time_charge: type: number prorated_amount: type: number required: - line_items - subtotal - total priceInfo: type: object properties: amount: type: number currency: type: string interval: type: string interval_count: type: number required: - amount - currency - interval - interval_count Model6: type: object properties: _subscription_type: $ref: '#/definitions/_subscription_type' created: type: number description: This is the date the subscription was created. current_period_end: type: number description: This is the end date of the current billing cycle. current_period_start: type: number description: This is the start date of the current billing cycle. cancel_at_period_end: type: boolean description: >- True if the subscription will not automatically renew at the end of the current billing period. Else false. end_at: type: number x-alternatives: - type: number - type: string failure_code: type: string description: Reason for the failure (e.g. insufficient funds, closed, frozen). failure_message: type: string description: >- Message from Stripe for the client making the request to further explain the reason for top-up failure if available. For more information about failure codes and messages from Stripe to the client, see [Stripe docs](https://stripe.com/docs/api/errors). It is suggested that the [error type](https://stripe.com/docs/api/errors#errors-message) of `type: card_error` is shown directly to the customer. latest_invoice: type: string description: The most recent invoice this subscription has generated from Stripe. latest_invoice_items: $ref: '#/definitions/latest_invoice_items' plan_id: type: string description: >- A unique identifier for the [plan](https://stripe.com/docs/api/plans/object). maxLength: 255 product_id: type: string description: >- A unique identifier for the [product](https://stripe.com/docs/api/products/object) purchased. maxLength: 255 product_name: type: string description: The name of the product purchased. priceInfo: $ref: '#/definitions/priceInfo' status: type: string description: >- The status of the product (e.g. `active`, `canceled`, `trialing`, `unpaid`, etc). subscription_id: type: string description: >- A unique identifier for the Stripe [subscription](https://stripe.com/docs/api/subscriptions/object). maxLength: 255 promotion_amount_off: type: integer description: >- Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer. minimum: 0 promotion_code: type: string description: A customer-redeemable code for a coupon. promotion_duration: type: string description: Indicates how long the coupon is valid for. promotion_end: type: number description: >- If the coupon has a duration of repeating, the date that this discount will end. If the coupon has a duration of once or forever, this attribute will be null. promotion_name: type: string description: >- Name of the coupon displayed to customers on for instance invoices or receipts. promotion_percent_off: type: number description: >- Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $100 invoice $50 instead. minimum: 0 maximum: 100 required: - created - current_period_end - current_period_start - cancel_at_period_end - latest_invoice - latest_invoice_items - plan_id - product_id - product_name - status - subscription_id subscriptions: type: array items: $ref: '#/definitions/Model6' Model7: type: object properties: createdAt: type: number passwordCreatedAt: type: number metricsOptOutAt: type: number hasPassword: type: boolean emails: $ref: '#/definitions/emails' linkedAccounts: $ref: '#/definitions/linkedAccounts' totp: $ref: '#/definitions/totp' backupCodes: $ref: '#/definitions/backupCodes' recoveryKey: $ref: '#/definitions/recoveryKey' recoveryPhone: $ref: '#/definitions/recoveryPhone' securityEvents: $ref: '#/definitions/securityEvents' subscriptions: $ref: '#/definitions/subscriptions' recoveryCodes: type: array minItems: 1 maxItems: 8 x-constraint: unique: true items: type: string minLength: 8 maxLength: 20 pattern: ^[a-zA-Z0-9]*$ Model8: type: object properties: recoveryCodes: $ref: '#/definitions/recoveryCodes' required: - recoveryCodes Model9: type: object properties: verified: type: boolean isPrimary: type: boolean email: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ required: - verified - isPrimary - email Model10: type: array items: $ref: '#/definitions/Model9' scope: type: array items: type: string maxLength: 256 pattern: ^[a-zA-Z0-9 _\/.:-]*$ location: type: object description: Object containing the client's state and country properties: city: type: string country: type: string state: type: string stateCode: type: string Model11: type: object properties: clientId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ deviceId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 sessionTokenId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ refreshTokenId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ isCurrentSession: type: boolean deviceType: type: string maxLength: 16 name: type: string maxLength: 255 createdTime: type: number minimum: 0 createdTimeFormatted: type: string lastAccessTime: type: number minimum: 0 lastAccessTimeFormatted: type: string approximateLastAccessTime: type: number minimum: 0 approximateLastAccessTimeFormatted: type: string scope: $ref: '#/definitions/scope' location: $ref: '#/definitions/location' userAgent: type: string maxLength: 255 os: type: string maxLength: 255 required: - clientId - deviceId - sessionTokenId - refreshTokenId - isCurrentSession - deviceType - name - createdTime - lastAccessTime - scope - userAgent Model12: type: array items: $ref: '#/definitions/Model11' Model13: type: object properties: clientId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ lastAccessTime: type: number minimum: 0 required: - clientId - lastAccessTime Model14: type: array x-constraint: unique: ignoreUndefined: true items: $ref: '#/definitions/Model13' Model15: type: object properties: id: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 isCurrentDevice: type: boolean lastAccessTime: type: number minimum: 0 lastAccessTimeFormatted: type: string approximateLastAccessTime: type: number minimum: 0 approximateLastAccessTimeFormatted: type: string location: $ref: '#/definitions/location' name: type: string maxLength: 255 type: type: string maxLength: 16 pushCallback: type: string maxLength: 255 pattern: >- ^https:\/\/[a-zA-Z0-9._-]+(\.services\.mozilla\.com|autopush\.dev\.mozaws\.net|autopush\.stage\.mozaws\.net)(?::\d+)?(\/.*)?$ x-format: uri: scheme: https pushPublicKey: type: string maxLength: 88 pattern: ^[A-Za-z0-9_-]+$ pushAuthKey: type: string maxLength: 24 pattern: ^[A-Za-z0-9_-]+$ pushEndpointExpired: type: boolean availableCommands: type: object properties: string: type: string maxLength: 2048 required: - id - isCurrentDevice - lastAccessTime - name - type Model16: type: array items: $ref: '#/definitions/Model15' Model17: type: object properties: bundle: type: string description: >- See [**decrypting the bundle**](https://wiki.mozilla.org/Identity/AttachedServices/KeyServerProtocol#Decrypting_the_getToken2_Response) for information on how to extract kA|wrapKb from the bundle. pattern: ^(?:[a-fA-F0-9]{2})+$ authenticationMethods: type: array items: type: string subscriptionsByClientId: type: object Model18: type: object properties: email: type: string locale: type: string authenticationMethods: $ref: '#/definitions/authenticationMethods' authenticatorAssuranceLevel: type: number minimum: 0 subscriptionsByClientId: $ref: '#/definitions/subscriptionsByClientId' profileChangedAt: type: number minimum: 0 metricsEnabled: type: boolean accountLockedAt: type: number accountDisabledAt: type: number keysChangedAt: type: number Model19: type: object properties: id: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ lastAccessTime: type: number minimum: 0 lastAccessTimeFormatted: type: string approximateLastAccessTime: type: number minimum: 0 approximateLastAccessTimeFormatted: type: string createdTime: type: number minimum: 0 createdTimeFormatted: type: string location: $ref: '#/definitions/location' userAgent: type: string maxLength: 255 os: type: string maxLength: 255 deviceId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 deviceName: type: string maxLength: 255 deviceAvailableCommands: type: object properties: string: type: string maxLength: 2048 deviceType: type: string maxLength: 16 deviceCallbackURL: type: string maxLength: 255 pattern: >- ^https:\/\/[a-zA-Z0-9._-]+(\.services\.mozilla\.com|autopush\.dev\.mozaws\.net|autopush\.stage\.mozaws\.net)(?::\d+)?(\/.*)?$ x-format: uri: scheme: https deviceCallbackPublicKey: type: string maxLength: 88 pattern: ^[A-Za-z0-9_-]+$ deviceCallbackAuthKey: type: string maxLength: 24 pattern: ^[A-Za-z0-9_-]+$ deviceCallbackIsExpired: type: boolean isDevice: type: boolean isCurrentDevice: type: boolean required: - id - lastAccessTime - createdTime - userAgent - deviceId - deviceName - deviceAvailableCommands - deviceType - deviceCallbackURL - deviceCallbackPublicKey - deviceCallbackAuthKey - deviceCallbackIsExpired - isDevice - isCurrentDevice Model20: type: array items: $ref: '#/definitions/Model19' Model21: type: object properties: id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) asking for permission. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 name: type: string description: A string name of the client. trusted: type: boolean description: Whether the client is a trusted internal application. image_uri: type: string description: A url to a logo or image that represents the client. redirect_uri: type: string description: >- The URI at which the connecting client expects to receive the authorization code and redirect to after a successful oauth. If supplied, this must match the URL value provided during OAuth client registration. required: - id - name - trusted - redirect_uri Model22: type: object properties: email: type: string verified: type: boolean sessionVerified: type: boolean emailVerified: type: boolean required: - email - verified details: type: object properties: accountEmailVerified: type: boolean sessionVerificationMethod: type: string sessionVerified: type: boolean sessionVerificationMeetsMinimumAAL: type: boolean verified: type: boolean Model23: type: object properties: state: type: string uid: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ details: $ref: '#/definitions/details' required: - state - uid Model24: type: object properties: exists: type: boolean verified: type: boolean payload: type: object data: type: object properties: command: type: string maxLength: 255 payload: $ref: '#/definitions/payload' sender: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 required: - command - payload Model25: type: object properties: index: type: number data: $ref: '#/definitions/data' required: - index - data messages: type: array description: An array of individual commands for the device to process. items: $ref: '#/definitions/Model25' Model26: type: object properties: index: type: number description: >- The largest index of the commands returned in this response. This value can be passed as the index parameter in subsequent calls in order to page through all the items. last: type: boolean description: >- Indicates whether more commands and enqueued than could be returned within the specific limit. messages: $ref: '#/definitions/messages' required: - index Model27: type: object properties: eligible: type: boolean required: - eligible Model28: type: object properties: id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) asking for permission. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 name: type: string description: A string name of the client. trusted: type: boolean description: Whether the client is a trusted internal application. image_uri: type: string description: A url to a logo or image that represents the client. redirect_uri: type: string description: >- The URI at which the connecting client expects to receive the authorization code and redirect to after a successful oauth. If supplied, this must match the URL value provided during OAuth client registration. required: - id - name - trusted - redirect_uri Model29: type: object properties: uid: type: string description: The user id. subscriptionId: type: string description: >- A unique identifier for the Stripe [subscription](https://stripe.com/docs/api/subscriptions/object). maxLength: 255 productId: type: string description: >- A unique identifier for the [product](https://stripe.com/docs/api/products/object) purchased. maxLength: 255 createdAt: type: number description: This is the date the subscription was created. cancelledAt: type: number x-alternatives: - type: number - type: string required: - uid - subscriptionId - productId - createdAt Model30: type: array items: $ref: '#/definitions/Model29' capabilities: type: array description: >- An array of RP-defined strings that represent a certain level of access to their product/service. items: type: string Model31: type: object properties: clientId: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) capabilities: $ref: '#/definitions/capabilities' Model32: type: array items: $ref: '#/definitions/Model31' plan_metadata: type: object description: >- Set of key-value pairs used to store additional information about the plan. For more information, see [Ecosystem Platform](https://mozilla.github.io/ecosystem-platform/tutorials/subscription-platform#stripe-plan-metadata) product_metadata: type: object description: >- Set of key-value pairs used to store additional information about the product. For more information, see [Ecosystem Platform](https://mozilla.github.io/ecosystem-platform/tutorials/subscription-platform#stripe-product-metadata) urls: type: object properties: successActionButton: type: string x-format: uri: true webIcon: type: string x-format: uri: true emailIcon: type: string x-format: uri: true termsOfService: type: string x-format: uri: true termsOfServiceDownload: type: string x-format: uri: true privacyNotice: type: string x-format: uri: true privacyNoticeDownload: type: string x-format: uri: true playStore: type: string x-format: uri: true appStore: type: string x-format: uri: true cancellationSurvey: type: string x-format: uri: true Model33: type: array items: type: string uiContent: type: object properties: name: type: string subtitle: type: string details: $ref: '#/definitions/Model33' successActionButtonLabel: type: string upgradeCTA: type: string styles: type: object properties: webIconBackground: type: string app: type: array items: type: string support: type: object properties: app: $ref: '#/definitions/app' string: type: object properties: uiContent: $ref: '#/definitions/uiContent' urls: $ref: '#/definitions/urls' support: $ref: '#/definitions/support' productSet: type: array items: type: string promotionCodes: type: array items: type: string playSkuIds: type: array items: type: string appStoreProductIds: type: array items: type: string configuration: type: object properties: id: type: string urls: $ref: '#/definitions/urls' uiContent: $ref: '#/definitions/uiContent' styles: $ref: '#/definitions/styles' locales: type: object properties: string: $ref: '#/definitions/string' support: $ref: '#/definitions/support' stripeProductId: type: string productSet: $ref: '#/definitions/productSet' promotionCodes: $ref: '#/definitions/promotionCodes' productConfigId: type: string stripePriceId: type: string productOrder: type: number playSkuIds: $ref: '#/definitions/playSkuIds' appStoreProductIds: $ref: '#/definitions/appStoreProductIds' required: - productSet Model34: type: object properties: plan_id: type: string description: >- A unique identifier for the [plan](https://stripe.com/docs/api/plans/object). maxLength: 255 plan_metadata: $ref: '#/definitions/plan_metadata' product_id: type: string description: >- A unique identifier for the [product](https://stripe.com/docs/api/products/object) purchased. maxLength: 255 product_name: type: string description: The name of the product purchased. plan_name: type: string description: The name of the plan. product_metadata: $ref: '#/definitions/product_metadata' interval: type: string description: >- The frequency at which a subscription is billed (e.g. day, week, month, year). interval_count: type: number description: >- The number of intervals between subscription billings (e.g. `interval=month` and `interval_count=3` bills every 3 months). amount: type: number description: >- Amount intended to be collected. A positive integer representing how much to charge in the smallest currency unit (e.g. 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). currency: type: string description: The three-letter ISO currency code, in lowercase. active: type: boolean description: Whether the price can be used for new purchases. Defaults to true. configuration: $ref: '#/definitions/configuration' required: - plan_id - product_id - product_name - interval - interval_count - amount - currency - active - configuration Model35: type: array items: $ref: '#/definitions/Model34' Model36: type: object properties: product_name: type: string description: The name of the product purchased. required: - product_name Model37: type: array description: A list of all subscriptions (including web and IAP). items: $ref: '#/definitions/Model6' Model38: type: object properties: customerId: type: string description: >- A unique identifier for the Stripe/PayPal [customer](https://stripe.com/docs/api/customers/object). billing_name: type: string x-alternatives: - type: string - type: string exp_month: type: number description: Two-digit number representing the card's expiration month. exp_year: type: number description: Four-digit number representing the card's expiration year. last4: type: string description: The last four digits of the card. payment_provider: type: string description: The payment processors (e.g. PayPal, Stripe). payment_type: type: string description: >- The type of the payment method (e.g., `credit`, `debit`, `prepaid`, or `unknown`). paypal_payment_error: type: string description: The payment error from PayPal encountered. brand: type: string description: >- Card brand (e.g. `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, or `unknown`). billing_agreement_id: type: string x-alternatives: - type: string - type: string subscriptions: $ref: '#/definitions/Model37' required: - subscriptions Model39: type: object properties: amount: type: number inclusive: type: boolean display_name: type: string required: - amount - inclusive Model40: type: array items: $ref: '#/definitions/Model39' Model41: type: object properties: currency: type: string subscriptionId: type: string period_start: type: number subtotal: type: number subtotal_excluding_tax: type: number total: type: number total_excluding_tax: type: number tax: $ref: '#/definitions/Model40' required: - currency - subscriptionId - period_start - subtotal - subtotal_excluding_tax - total - total_excluding_tax Model42: type: array items: $ref: '#/definitions/Model41' response_type: type: string description: >- If supplied, must be either code or token. code is the default. token means the implicit grant is desired, and requires that the client have special permission to do so. - Note: new implementations should not use `response_type=token`; instead use `grant_type=fxa-credentials` at the [token][] endpoint. default: code enum: - code - token access_type: type: string description: >- If specified, a value of `offline` will cause the connecting client to be granted a refresh token alongside its access token. default: online enum: - offline - online code_challenge_method: type: string description: >- Required for public OAuth clients, who must authenticate their authorization code use via [**PKCE**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/fxa-oauth-server/docs/pkce.md). The only support method is 'S256', no other value is accepted. enum: - S256 Model43: type: object properties: client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) returned from client registration. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 assertion: type: string description: A FxA assertion for the signed-in user. minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ redirect_uri: type: string description: >- The URI at which the connecting client expects to receive the authorization code and redirect to after a successful oauth. If supplied, this must match the URL value provided during OAuth client registration. maxLength: 256 x-format: uri: scheme: - https scope: type: string description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. response_type: $ref: '#/definitions/response_type' state: type: string description: >- An opaque string value provided by the connecting client application, which will be returned unmodified upon redirection alongside the authorization code. This can be used by the connecting client guard against certain classes of attack in the redirect-based OAuth flow to verify that the redirect is authentic. maxLength: 512 ttl: type: number description: >- Indicates the requested lifespan in seconds for the `access_token` or implicit grant token. If unspecified, the value will default to an internal maximum limit allowed by the server, which is a configurable option, so clients must check the `expires_in` result property for the actual TTL - it is typically measured in minutes or hours.undefined default: 86400 x-constraint: sign: positive access_type: $ref: '#/definitions/access_type' code_challenge_method: $ref: '#/definitions/code_challenge_method' code_challenge: type: string description: >- Required for public OAuth clients, who must authenticate their authorization code use via [**PKCE**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/fxa-oauth-server/docs/pkce.md). A minimum length of 43 characters and a maximum length of 128 characters string, encoded as `BASE64URL`. x-constraint: length: 43 keys_jwe: type: string description: >- An encrypted JWE bundle of key material, to be returned to the client when it redeems the authorization code. maxLength: 1024 pattern: >- ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$ acr_values: type: string description: >- A space-separated list of ACR values specifying acceptable levels of user authentication that the token should have a claim for. Specifying `AAL2` will require the token to have an authentication assuarance level >= 2 which ensures that the user has been authenticated with 2FA before authorizing the requested grant. maxLength: 256 resource: type: string description: >- Indicates the target service or resource at which access is being requested. Its value must be an absolute URI, and may include a query component but must not include a fragment component. Added to the `aud` claim of JWT access tokens. Optional if `response_type=token`, forbidden if `response_type=code`. pattern: '#' x-format: uri: true required: - client_id - assertion - scope - code_challenge_method token_type: type: string description: >- The type of token, which determines how the client should use it in subsequent requests. Currently only Bearer tokens are supported. enum: - bearer Model44: type: object properties: redirect: type: string code: type: string description: >- A string that the client will trade with the [token][] endpoint. Codes have a configurable expiration value, default is 15 minutes. Codes are single use only. state: type: string description: >- An opaque string value provided by the connecting client application, which will be returned unmodified upon redirection alongside the authorization code. This can be used by the connecting client guard against certain classes of attack in the redirect-based OAuth flow to verify that the redirect is authentic. access_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ token_type: $ref: '#/definitions/token_type' scope: type: string description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. auth_at: type: number description: >- The UTC unix timestamp for the session at which the user last authenticated to FxA server when generating this token, in seconds since the epoch. expires_in: type: number description: The number of seconds until the access token will expire. Model45: type: object properties: assertion: type: string description: A FxA assertion for the signed-in user. minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ required: - assertion Model46: type: array description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. items: type: string Model47: type: object properties: client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 refresh_token_id: type: string description: The specific `refresh_token_id` to be destroyed. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 client_name: type: string description: The string name of the client. created_time: type: number description: Integer time of token creation. minimum: 0 last_access_time: type: number description: Integer last-access time for the token. minimum: 0 scope: $ref: '#/definitions/Model46' required: - client_id - client_name - created_time - last_access_time - scope Model48: type: array items: $ref: '#/definitions/Model47' Model49: type: object properties: client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 client_secret: type: string description: >- The OAuth client secret for the requesting client application. Required for confidential clients, forbidden for public clients. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 access_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ refresh_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 refresh_token_id: type: string description: The specific `refresh_token_id` to be destroyed. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 token_type_hint: type: string description: >- A hint as to what type of token is being revoked. Expected values are "access_token" or "refresh_token", Unrecognized values will be silently ignored, and specifying an incorrect hint may cause to the request to take longer but will still result in the token being destroyed. enum: - access_token - refresh_token Model50: type: object properties: token: type: string description: An OAuth token string received from a client for the user token_type_hint: $ref: '#/definitions/token_type_hint' required: - token Model51: type: string description: >- A string representing the token type. It will be `access_token` or `refresh_token` enum: - access_token - refresh_token Model52: type: object properties: active: type: boolean description: Boolean indicator of whether the presented token is active. scope: type: string description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 token_type: $ref: '#/definitions/Model51' exp: type: number description: Integer time of token expiration. iat: type: number description: Integer time of token creation. sub: type: string description: The hex id of the user. iss: type: string jti: type: string description: The hex id of the token. fxa-lastUsedAt: type: number description: ' Integer time when this token is last used.' required: - active Model53: type: object properties: client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 assertion: type: string description: A FxA assertion for the signed-in user. minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ scope: type: string description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. required: - client_id - assertion - scope Model54: type: object properties: identifier: type: string keyRotationSecret: type: string keyRotationTimestamp: type: number required: - identifier - keyRotationSecret - keyRotationTimestamp Model55: type: string enum: - firefox-accounts-journey - knowledge-is-power - mozilla-foundation - take-action-for-the-internet - test-pilot - mozilla-and-you - security-privacy-news - mozilla-accounts - hubs - mdnplus newsletters: type: array items: $ref: '#/definitions/Model55' Model56: type: object properties: newsletters: $ref: '#/definitions/newsletters' required: - newsletters Model57: type: object properties: success: type: boolean Model58: type: object properties: recoveryKeyId: type: string description: >- A unique identifier for this account recovery key, derived from the key via HKDF. maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ recoveryData: type: string description: An encrypted bundle containing the user's kB. maxLength: 1024 pattern: '[a-zA-Z0-9.]' enabled: type: boolean default: true replaceKey: type: boolean default: false required: - recoveryData grant_type: type: string description: |- - If `authorization_code`: - `client_id`: The id returned from client registration. - `client_secret`: The secret returned from client registration. Forbidden for public clients, required otherwise. - `code`: A string that was received from the [authorization][] endpoint. - `code_verifier`: The [PKCE](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/oauth/pkce.md) code verifier. Required for public clients, forbidden otherwise. - If `refresh_token`: - `client_id`: The id returned from client registration. - `client_secret`: The secret returned from client registration. Forbidden for public (PKCE) clients, required otherwise. - `refresh_token`: A string that received from the [token][] endpoint specifically as a refresh token. - `scope`: (optional) A subset of scopes provided to this refresh_token originally, to receive an access_token with less permissions. - If `fxa-credentials`: - `client_id`: The id returned from client registration. - `assertion`: FxA identity assertion authenticating the user. - `scope`: (optional) A string-separated list of scopes to be authorized. - `access_type`: (optional) Determines whether to generate a `refresh_token` (if `offline`) or not (if `online`). default: authorization_code enum: - authorization_code - refresh_token - fxa-credentials - urn:ietf:params:oauth:grant-type:token-exchange subject_token_type: type: string description: >- A URN identifying the type of subject_token. Must be `urn:ietf:params:oauth:token-type:refresh_token` to indicate the subject_token is a refresh token. enum: - urn:ietf:params:oauth:token-type:refresh_token Model59: type: object properties: client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 client_secret: type: string description: >- The OAuth client secret for the requesting client application. Required for confidential clients, forbidden for public clients. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 redirect_uri: type: string description: >- The URI at which the connecting client expects to receive the authorization code and redirect to after a successful oauth. If supplied, this must match the URL value provided during OAuth client registration. maxLength: 256 pattern: ^[a-zA-Z0-9\-_\/.:?=&]+$ grant_type: $ref: '#/definitions/grant_type' ttl: type: number description: >- Indicates the requested lifespan in seconds for the `access_token` or implicit grant token. If unspecified, the value will default to an internal maximum limit allowed by the server, which is a configurable option, so clients must check the `expires_in` result property for the actual TTL - it is typically measured in minutes or hours. default: 86400 x-constraint: sign: positive scope: type: string required: - scope optional: - scope x-alternatives: - type: string - type: string - type: string access_type: $ref: '#/definitions/access_type' code: type: string description: >- A string that the client will trade with the [token][] endpoint. Codes have a configurable expiration value, default is 15 minutes. Codes are single use only. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 code_verifier: type: string description: >- The [PKCE](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/oauth/pkce.md) code verifier. Required for public clients, forbidden otherwise. minLength: 43 maxLength: 128 pattern: ^[A-Za-z0-9-_]+$ refresh_token: type: string description: >- A token that can be used to grant a new access token when the current one expires, via `grant_type=refresh_token` on this endpoint. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 assertion: type: string description: A FxA assertion for the signed-in user. minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ subject_token: type: string description: >- The token to be exchanged. Used with `grant_type=urn:ietf:params:oauth:grant-type:token-exchange` per RFC 8693. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 subject_token_type: $ref: '#/definitions/subject_token_type' ppid_seed: type: integer description: >- Seed used in `sub` claim generation of JWT access tokens/ID tokens for clients with [Pseudonymous Pairwise Identifiers (PPID)](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/oauth/pairwise-pseudonymous-identifiers.md) enabled. Used to forcibly rotate the `sub` claim. Must be an integer in the range 0-1024. If not specified, it will default to `0`. default: 0 minimum: 0 maximum: 1024 resource: type: string description: >- Indicates the target service or resource at which access is being requested. Its value must be an absolute URI, and may include a query component but must not include a fragment component. Added to the `aud` claim of JWT access tokens. pattern: '#' x-format: uri: true required: - client_id - client_secret - code - refresh_token - assertion - subject_token - subject_token_type Model60: type: object properties: access_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ refresh_token: type: string description: >- A refresh token to fetch a new access token when this one expires. Only present if: - `grant_type=authorization_code` and the original authorization request included `access_type=offline`. - `grant_type=fxa-credentials` and the request included `access_type=offline`. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 id_token: type: string description: >- OpenID Connect identity token, provisioned if the authorization was requested with `openid` scope. minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ session_token_id: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 scope: type: string description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. token_type: $ref: '#/definitions/token_type' expires_in: type: number description: The number of seconds until the access token will expire. maximum: 86400 auth_at: type: number description: >- The UTC unix timestamp for the session at which the user last authenticated to FxA server when generating this token, in seconds since the epoch. keys_jwe: type: string description: >- Returns the JWE bundle of key material for any scopes that have keys, if `grant_type=authorization_code` maxLength: 1024 pattern: >- ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$ required: - access_token - scope - token_type - expires_in Model61: type: object properties: token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ required: - token Model62: type: array description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. items: type: string Model63: type: object properties: user: type: string description: The uid of the respective user. client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) scope: $ref: '#/definitions/Model62' generation: type: number minimum: 0 profile_changed_at: type: number minimum: 0 required: - user - client_id utmCampaign: type: string enum: - page+referral+-+not+part+of+a+campaign maxLength: 128 pattern: ^[\w\/.%-]+$ metricsContext: type: object properties: deviceId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 entrypoint: type: string maxLength: 128 pattern: ^[\w.:-]+$ entrypointExperiment: type: string maxLength: 128 pattern: ^[\w.:-]+$ entrypointVariation: type: string maxLength: 128 pattern: ^[\w.:-]+$ flowId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 flowBeginTime: type: integer x-constraint: sign: positive utmCampaign: $ref: '#/definitions/utmCampaign' utmContent: type: string maxLength: 128 pattern: ^[\w\/.%-]+$ utmMedium: type: string maxLength: 128 pattern: ^[\w\/.%-]+$ utmSource: type: string maxLength: 128 pattern: ^[\w\/.%-]+$ utmTerm: type: string maxLength: 128 pattern: ^[\w\/.%-]+$ productId: type: string maxLength: 128 planId: type: string maxLength: 128 clientId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 16 service: type: string maxLength: 128 style: type: string enum: - trailhead verificationMethod: type: string description: >- If this param is specified, it forces the login to be verified using the specified method. Currently supported methods: - `email`: Sends an email with a confirmation link. - `email-2fa`: Sends an email with a confirmation code. - `email-captcha`: Sends an email with an unblock code. enum: - email - email-otp - email-2fa - email-captcha - totp-2fa Model64: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPWVersion2: type: string description: >- The PBKDF2/HKDF-stretched password as a hex string using the version 2 key stretching. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKb: type: string description: The new `wrapKb` value as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKbVersion2: type: string description: The new `wrapKb` value for authPW2 as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 clientSalt: type: string description: >- The salt used when creating authPW. If not provided, it will be assumed that version one of the password encryption scheme was used. pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: service: type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ redirectTo: type: string description: >- URL that the client should be redirected to after handling the request. maxLength: 2048 resume: type: string description: >- Opaque URL-encoded string to be included in the verification link as a query parameter. maxLength: 2048 metricsContext: $ref: '#/definitions/metricsContext' style: $ref: '#/definitions/style' verificationMethod: $ref: '#/definitions/verificationMethod' required: - email - authPW Model65: type: object properties: uid: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ sessionToken: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ keyFetchToken: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ keyFetchTokenVersion2: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ authAt: type: integer description: >- The UTC unix timestamp for the session at which the user last authenticated to FxA server when generating this token, in seconds since the epoch. verificationMethod: $ref: '#/definitions/verificationMethod' required: - uid - sessionToken Model66: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 required: - email - authPW Model67: type: array x-constraint: length: 0 items: type: string Model68: type: object properties: id: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 name: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ type: type: string maxLength: 16 pushCallback: type: string maxLength: 255 pattern: >- ^https:\/\/[a-zA-Z0-9._-]+(\.services\.mozilla\.com|autopush\.dev\.mozaws\.net|autopush\.stage\.mozaws\.net)(?::\d+)?(\/.*)?$ x-format: uri: scheme: https pushPublicKey: type: string maxLength: 88 pattern: ^[A-Za-z0-9_-]+$ pushAuthKey: type: string maxLength: 24 pattern: ^[A-Za-z0-9_-]+$ availableCommands: type: object properties: string: type: string maxLength: 2048 capabilities: $ref: '#/definitions/Model67' Model69: type: object properties: id: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 createdAt: type: number x-constraint: sign: positive name: type: string maxLength: 255 type: type: string maxLength: 16 pushCallback: type: string maxLength: 255 pattern: >- ^https:\/\/[a-zA-Z0-9._-]+(\.services\.mozilla\.com|autopush\.dev\.mozaws\.net|autopush\.stage\.mozaws\.net)(?::\d+)?(\/.*)?$ x-format: uri: scheme: https pushPublicKey: type: string maxLength: 88 pattern: ^[A-Za-z0-9_-]+$ pushAuthKey: type: string maxLength: 24 pattern: ^[A-Za-z0-9_-]+$ pushEndpointExpired: type: boolean availableCommands: type: object properties: string: type: string maxLength: 2048 required: - id Model70: type: object properties: email: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ required: - email Model71: type: object properties: hasHardBounce: type: boolean required: - hasHardBounce Model72: type: object properties: token: type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKb: type: string description: The new `wrapKb` value as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPWVersion2: type: string description: >- The PBKDF2/HKDF-stretched password as a hex string using the version 2 key stretching. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKbVersion2: type: string description: The new `wrapKb` value for authPW2 as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 clientSalt: type: string description: >- The salt used when creating authPW. If not provided, it will be assumed that version one of the password encryption scheme was used. pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: required: - authPW Model73: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 service: type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ redirectTo: type: string maxLength: 2048 resume: type: string description: >- Opaque URL-encoded string to be included in the verification link as a query parameter. reason: type: string description: >- Alphanumeric string indicating the reason for establishing a new session; may be "login" (the default) or "reconnect". maxLength: 16 unblockCode: type: string description: Alphanumeric code used to unblock certain rate-limitings. pattern: ^[a-zA-Z0-9]*$ x-constraint: length: 8 metricsContext: $ref: '#/definitions/metricsContext' originalLoginEmail: type: string description: >- This parameter is the original email used to login with. Typically, it is specified after a user logins with a different email case, or changed their primary email address. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ verificationMethod: $ref: '#/definitions/verificationMethod' required: - email - authPW Model74: type: object properties: uid: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ sessionToken: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ keyFetchToken: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ keyFetchTokenVersion2: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ verificationMethod: type: string description: >- If this param is specified, it forces the login to be verified using the specified method. Currently supported methods: - `email`: Sends an email with a confirmation link. - `email-2fa`: Sends an email with a confirmation code. - `email-captcha`: Sends an email with an unblock code. verificationReason: type: string description: The authentication method that required additional verification. emailVerified: type: boolean sessionVerified: type: boolean verified: type: boolean authAt: type: integer description: >- The UTC unix timestamp for the session at which the user last authenticated to FxA server when generating this token, in seconds since the epoch. metricsEnabled: type: boolean required: - uid - sessionToken - emailVerified - sessionVerified - verified - metricsEnabled state: type: string enum: - in - out Model75: type: object properties: state: $ref: '#/definitions/state' required: - state Model76: type: object properties: authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPWVersion2: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKb: type: string description: The new `wrapKb` value as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKbVersion2: type: string description: The new `wrapKb` value for authPW2 as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 clientSalt: type: string description: >- The salt used when creating authPW. If not provided, it will be assumed that version one of the password encryption scheme was used. pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: recoveryKeyId: type: string description: >- A unique identifier for this account recovery key, derived from the key via HKDF. maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ sessionToken: type: boolean description: >- Indicates whether a new `sessionToken` is required, default to `false`. isFirefoxMobileClient: type: boolean description: Is this a Firefox mobile client? required: - authPW Model77: type: object properties: client_id: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 scope: type: string required: - client_id - scope any: type: object properties: identifier: type: string keyRotationSecret: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 keyRotationTimestamp: type: number required: - identifier - keyRotationSecret - keyRotationTimestamp Model78: type: object properties: authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPWVersion2: type: string description: >- The PBKDF2/HKDF-stretched password as a hex string using the version 2 key stretching. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKb: type: string description: The new `wrapKb` value as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKbVersion2: type: string description: The new `wrapKb` value for authPW2 as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 clientSalt: type: string description: >- The salt used when creating authPW. If not provided, it will be assumed that version one of the password encryption scheme was used. pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: metricsContext: $ref: '#/definitions/metricsContext' service: type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ required: - authPW Model79: type: object properties: sessionToken: type: string description: >- Indicates whether a new `sessionToken` is required, default to `false`. pattern: ^(?:[a-fA-F0-9]{2})+$ uid: type: string description: The user id. pattern: ^(?:[a-fA-F0-9]{2})+$ required: - sessionToken - uid Model80: type: object properties: email: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ thirdPartyAuthStatus: type: boolean default: false checkDomain: type: string clientId: type: string service: type: string maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ required: - email Model81: type: object properties: exists: type: boolean hasLinkedAccount: type: boolean hasPassword: type: boolean invalidDomain: type: boolean passwordlessSupported: type: boolean required: - exists Model82: type: object properties: email: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ clientId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 16 metricsContext: $ref: '#/definitions/metricsContext' required: - email - clientId Model83: type: object properties: client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) whose tokens should be deleted. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 refresh_token_id: type: string description: The specific `refresh_token_id` to be destroyed. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 assertion: type: string description: A FxA assertion for the signed-in user. minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ required: - client_id provider: type: string enum: - google - apple maxLength: 256 Model84: type: object properties: idToken: type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ provider: $ref: '#/definitions/provider' code: type: string metricsContext: $ref: '#/definitions/metricsContext' service: type: string maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ required: - provider Model85: type: object properties: uid: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ sessionToken: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ providerUid: type: string description: The user id associated with a particular third party provider. email: type: string description: The primary email for this account. verificationMethod: type: string description: >- If this param is specified, it forces the login to be verified using the specified method. Currently supported methods: - `email`: Sends an email with a confirmation link. - `email-2fa`: Sends an email with a confirmation code. - `email-captcha`: Sends an email with an unblock code. required: - uid - sessionToken - providerUid - email Model86: type: object properties: provider: $ref: '#/definitions/provider' required: - provider Model87: type: object properties: success: type: boolean required: - success Model88: type: object properties: success: type: boolean Model89: type: object properties: recoveryKeyId: type: string description: >- A unique identifier for this account recovery key, derived from the key via HKDF. maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ recoveryData: type: string description: An encrypted bundle containing the user's kB. maxLength: 1024 pattern: '[a-zA-Z0-9.]' enabled: type: boolean default: true replaceKey: type: boolean default: false required: - recoveryData Model90: type: object properties: email: type: string description: The email address to add to the account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ required: - email Model91: type: string description: >- Determines the format of the response. Since we only support the authorization-code grant flow, the only permitted value is 'code'. default: code enum: - code Model92: type: object properties: response_type: $ref: '#/definitions/Model91' client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 redirect_uri: type: string description: >- The URI at which the connecting client expects to receive the authorization code and redirect to after a successful oauth. If supplied, this must match the URL value provided during OAuth client registration. maxLength: 256 x-format: uri: scheme: - http - https scope: type: string description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. state: type: string description: >- An opaque string value provided by the connecting client application, which will be returned unmodified upon redirection alongside the authorization code. This can be used by the connecting client guard against certain classes of attack in the redirect-based OAuth flow to verify that the redirect is authentic. maxLength: 512 access_type: $ref: '#/definitions/access_type' code_challenge_method: $ref: '#/definitions/code_challenge_method' code_challenge: type: string description: >- Required for public OAuth clients, who must authenticate their authorization code use via [**PKCE**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/fxa-oauth-server/docs/pkce.md). A minimum length of 43 characters and a maximum length of 128 characters string, encoded as `BASE64URL`. pattern: ^[A-Za-z0-9_-]+$ x-constraint: length: 43 keys_jwe: type: string description: >- An encrypted JWE bundle of key material, to be returned to the client when it redeems the authorization code. maxLength: 1024 pattern: >- ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$ acr_values: type: string description: >- A space-separated list of ACR values specifying acceptable levels of user authentication that the token should have a claim for. Specifying `AAL2` will require the token to have an authentication assuarance level >= 2 which ensures that the user has been authenticated with 2FA before authorizing the requested grant. maxLength: 256 required: - client_id - state Model93: type: object properties: redirect: type: string code: type: string state: type: string maxLength: 512 Model94: type: object properties: client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 client_secret: type: string description: >- The OAuth client secret for the requesting client application. Required for confidential clients, forbidden for public clients. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ - type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 token_type_hint: type: string description: >- A hint as to what type of token is being revoked. Expected values are "access_token" or "refresh_token", Unrecognized values will be silently ignored, and specifying an incorrect hint may cause to the request to take longer but will still result in the token being destroyed. maxLength: 64 required: - client_id Model95: type: object properties: client_id: type: string id_token: type: string expiry_grace_period: type: number default: 0 required: - client_id - id_token amr: type: array items: type: string Model96: type: object properties: acr: type: string aud: type: string alg: type: string at_hash: type: string amr: $ref: '#/definitions/amr' exp: type: number fxa-aal: type: number iat: type: number iss: type: string sub: type: string Model97: type: string description: >- The type of grant flow being used. If not specified, it will default to fxa-credentials unless a code parameter is provided, in which case it will default to authorization_code. The value of this parameter determines which other parameters will be expected in the request body, as follows: - When `grant_type=authorization_code`: - `code`: *validators.authorizationCode, required* The authorization code previously obtained through a redirect-based OAuth flow. - `code_verifier`: *validators.pkceCodeVerifier, optional* The [**PKCE**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/fxa-oauth-server/docs/pkce.md) code verifier used when obtaining code. This is required for public OAuth clients, who must authenticate their authorization code use via PKCE. - `redirect_uri`: *string, URI, optional* The URI at which the client received the authorization code. If supplied this must match the value provided during OAuth client registration. - When `grant_type=refresh_token`: - `refresh_token`: *validators.refreshToken, required* A refresh token, as issued by a previous call to this endpoint. - `scope`: *string, optional* A space-separated list of scope values that will be held by the generated token. These must be a subset of the scopes originally granted when the refresh token was generated. - When `grant_type=fxa-credentials`: - `scope`: *string, optional* A space-separated list of scope values that will be held by the generated tokens. - `access_type`: *string, valid(online, offline), optional* If specified, a value of offline will cause the client to be granted a refresh token alongside its access token. -In addition, the request must be authenticated with a sessionToken. default: authorization_code enum: - authorization_code Model98: type: object properties: grant_type: $ref: '#/definitions/Model97' client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 client_secret: type: string description: >- The OAuth client secret for the requesting client application. Required for confidential clients, forbidden for public clients. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 code: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 code_verifier: type: string minLength: 43 maxLength: 128 pattern: ^[A-Za-z0-9-\._~]{43,128}$ redirect_uri: type: string x-format: uri: true ttl: type: number description: >- The desired lifetime of the issued access token, in seconds. The actual lifetime may be smaller than requested depending on server configuration, and will be returned in the `expired_in` property of the response. x-constraint: sign: positive ppid_seed: type: integer description: >- Seed used in `sub` claim generation of JWT access tokens/ID tokens for clients with [Pseudonymous Pairwise Identifiers (PPID)](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/oauth/pairwise-pseudonymous-identifiers.md) enabled. Used to forcibly rotate the `sub` claim. Must be an integer in the range 0-1024. If not specified, it will default to `0`. default: 0 minimum: 0 maximum: 1024 resource: type: string description: >- Indicates the target service or resource at which access is being requested. Its value must be an absolute URI, and may include a query component but must not include a fragment component. Added to the `aud` claim of JWT access tokens. pattern: '#' x-format: uri: true required: - client_id - code Model99: type: object properties: access_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ refresh_token: type: string description: >- A token that can be used to grant a new access token when the current one expires, via `grant_type=refresh_token` on this endpoint. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 id_token: type: string description: >- OpenID Connect identity token, provisioned if the authorization was requested with `openid` scope. minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ session_token: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 scope: type: string description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. token_type: $ref: '#/definitions/token_type' expires_in: type: number description: The number of seconds until the access token will expire. auth_at: type: number description: >- The UTC unix timestamp for the session at which the user last authenticated to FxA server when generating this token, in seconds since the epoch. keys_jwe: type: string maxLength: 1024 pattern: >- ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$ required: - access_token - scope - token_type - expires_in - auth_at Model100: type: object properties: authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPWVersion2: type: string description: >- The PBKDF2/HKDF-stretched password as a hex string using the version 2 key stretching. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKb: type: string description: The new `wrapKb` value as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKbVersion2: type: string description: The new `wrapKb` value for authPW2 as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 clientSalt: type: string description: >- The salt used when creating authPW. If not provided, it will be assumed that version one of the password encryption scheme was used. pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: required: - authPW Model101: type: object properties: email: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ Model102: type: object properties: exists: type: boolean hint: type: string estimatedSyncDeviceCount: type: number required: - exists Model103: type: object properties: hint: type: string description: >- A string containing a user-defined hint to help them remember where they stored their account recovery key. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ Model104: type: object properties: recoveryKeyId: type: string maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ type: type: string enum: - upgradeSession maxLength: 32 x-format: alphanum: true Model105: type: object properties: email: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ service: type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ redirectTo: type: string maxLength: 2048 resume: type: string description: >- Opaque URL-encoded string to be included in the verification link as a query parameter. maxLength: 2048 style: $ref: '#/definitions/style' type: $ref: '#/definitions/type' Model106: type: string enum: - firefox-accounts-journey - knowledge-is-power - mozilla-foundation - take-action-for-the-internet - test-pilot - mozilla-and-you - security-privacy-news - mozilla-accounts - hubs - mdnplus Model107: type: array items: $ref: '#/definitions/Model106' Model108: type: object properties: uid: type: string maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ code: type: string minLength: 32 maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ service: type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ reminder: type: string description: Indicates that verification originates from a reminder email. pattern: ^(?:first|second|final)$ type: type: string description: The type of code being verified. maxLength: 32 x-format: alphanum: true style: $ref: '#/definitions/style' marketingOptIn: type: boolean newsletters: $ref: '#/definitions/Model107' required: - uid - code Model109: type: object properties: code: type: string minLength: 6 maxLength: 8 Model110: type: object properties: phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ required: - phoneNumber Model111: type: object properties: customSessionToken: type: string description: Custom session token id to destroy. minLength: 64 maxLength: 64 pattern: ^(?:[a-fA-F0-9]{2})+$ Model112: type: object properties: reason: type: string maxLength: 16 Model113: type: object properties: uid: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ sessionToken: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ authAt: type: integer emailVerified: type: boolean sessionVerified: type: boolean verificationMethod: type: string verificationReason: type: string verified: type: boolean required: - uid - sessionToken Model114: type: string enum: - email - email-otp - email-2fa - email-captcha - totp-2fa Model115: type: object properties: email: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ authPW: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 service: type: string maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ redirectTo: type: string maxLength: 2048 resume: type: string reason: type: string maxLength: 16 unblockCode: type: string pattern: ^[a-zA-Z0-9]*$ x-constraint: length: 8 metricsContext: $ref: '#/definitions/metricsContext' originalLoginEmail: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ verificationMethod: $ref: '#/definitions/Model114' required: - email - authPW Model116: type: object properties: uid: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ keyFetchToken: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ verificationMethod: type: string verificationReason: type: string emailVerified: type: boolean sessionVerified: type: boolean authAt: type: integer metricsEnabled: type: boolean verified: type: boolean required: - uid - emailVerified - sessionVerified - metricsEnabled - verified scopes: type: array items: type: string maxLength: 256 pattern: ^[a-zA-Z0-9 _\/.:-]*$ Model117: type: string enum: - firefox-accounts-journey - knowledge-is-power - mozilla-foundation - take-action-for-the-internet - test-pilot - mozilla-and-you - security-privacy-news - mozilla-accounts - hubs - mdnplus Model118: type: array items: $ref: '#/definitions/Model117' Model119: type: object properties: code: type: string pattern: ^[0-9]+$ service: type: string maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ scopes: $ref: '#/definitions/scopes' marketingOptIn: type: boolean newsletters: $ref: '#/definitions/Model118' metricsContext: $ref: '#/definitions/metricsContext' Model120: type: object properties: email: type: string maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ productName: type: string productPlatform: type: string productVersion: type: string topic: type: string app: type: string subject: type: string message: type: string product: type: string category: type: string required: - productName - topic - message Model121: type: object properties: success: type: boolean ticket: type: number error: type: string required: - success Model122: type: object properties: metricsContext: $ref: '#/definitions/metricsContext' Model123: type: object properties: qrCodeUrl: type: string secret: type: string required: - qrCodeUrl - secret Model124: type: object properties: code: type: string description: The TOTP code to check maxLength: 32 pattern: ^[0-9]+$ required: - code Model125: type: object properties: success: type: boolean Model126: type: object properties: clientId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 16 sessionTokenId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ refreshTokenId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 deviceId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 Model127: type: object Model128: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ currentVersion: type: string enum: - v1 - v2 Model129: type: object properties: currentVersion: $ref: '#/definitions/currentVersion' clientSalt: type: string pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: upgradeNeeded: type: boolean Model130: type: object properties: id: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 required: - id Model131: type: object Model132: type: object description: Opaque payload to be forwarded to the device. Model133: type: object properties: target: type: string description: The id of the device on which to invoke the command. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 command: type: string description: >- The id of the command to be invoked, as found in the device's availableCommands set. payload: $ref: '#/definitions/Model132' ttl: type: integer description: >- The time in milliseconds after which the command should expire, if not processed by the device. minimum: 0 maximum: 10000000 required: - target - command - payload Model134: type: object properties: enqueued: type: boolean notified: type: boolean notifyError: type: string to: type: string description: >- Devices to notify. String `'all'` or an array containing the relevant device ids. enum: - all _endpointAction: type: string enum: - accountVerify excluded: type: array description: >- Array of device ids to exclude from the notification. Ignored unless `to:"all"` is specified. items: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 Model135: type: object description: >- Push payload, validated against [**pushpayloads.schema.json**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/lib/pushpayloads.schema.json). Model136: type: object properties: to: $ref: '#/definitions/to' _endpointAction: $ref: '#/definitions/_endpointAction' excluded: $ref: '#/definitions/excluded' payload: $ref: '#/definitions/Model135' TTL: type: integer description: Push notification TTL, defaults to `0`. minimum: 0 required: - to - payload Model137: type: object Model138: type: object properties: uid: type: string description: The user id. maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ unblockCode: type: string description: Alphanumeric code used to unblock certain rate-limitings. pattern: ^[a-zA-Z0-9]*$ x-constraint: length: 8 required: - uid - unblockCode Model139: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ metricsContext: $ref: '#/definitions/metricsContext' required: - email Model140: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ code: type: string description: The OTP code sent to the user email pattern: ^[0-9]+$ x-constraint: length: 8 clientId: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 16 service: type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ metricsContext: $ref: '#/definitions/metricsContext' required: - email - code Model141: type: string enum: - totp-2fa verificationReason: type: string enum: - login Model142: type: object properties: uid: type: string sessionToken: type: string verified: type: boolean authAt: type: number isNewAccount: type: boolean verificationMethod: $ref: '#/definitions/Model141' verificationReason: $ref: '#/definitions/verificationReason' required: - uid - sessionToken - verified - authAt - isNewAccount Model143: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ clientId: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 16 service: type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ metricsContext: $ref: '#/definitions/metricsContext' required: - email Model144: type: object Model145: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ clientId: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 16 service: type: string description: Opaque alphanumeric token to be included in verification links. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ metricsContext: $ref: '#/definitions/metricsContext' required: - email Model146: type: object Model147: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ oldAuthPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPWVersion2: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKb: type: string description: The new `wrapKb` value as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKbVersion2: type: string description: The new `wrapKb` value for authPW2 as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 clientSalt: type: string description: >- The salt used when creating authPW. If not provided, it will be assumed that version one of the password encryption scheme was used. pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: required: - oldAuthPW - authPW Model148: type: object properties: authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPWVersion2: type: string description: >- The PBKDF2/HKDF-stretched password as a hex string using the version 2 key stretching. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKb: type: string description: The new `wrapKb` value as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKbVersion2: type: string description: The new `wrapKb` value for authPW2 as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 clientSalt: type: string description: >- The salt used when creating authPW. If not provided, it will be assumed that version one of the password encryption scheme was used. pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: required: - authPW Model149: type: object properties: email: type: string description: The email address to delete. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ required: - email Model150: type: object properties: email: type: string description: The new primary email address of the user. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ required: - email Model151: type: object properties: code: type: string minLength: 6 maxLength: 8 Model152: type: object properties: phoneNumber: type: string pattern: ^\+[1-9]\d{1,14}$ required: - phoneNumber Model153: type: object properties: metricsContext: $ref: '#/definitions/metricsContext' Model154: type: object properties: qrCodeUrl: type: string secret: type: string required: - qrCodeUrl - secret Model155: type: object properties: priceId: type: string description: >- A unique identifier for the [price](https://stripe.com/docs/api/prices/object). maxLength: 255 promotionCode: type: string description: A customer-redeemable code for a coupon. required: - priceId - promotionCode Model156: type: object properties: promotionCode: type: string type: type: string durationInMonths: type: number valid: type: boolean discountAmount: type: number expired: type: boolean maximallyRedeemed: type: boolean required: - promotionCode - type - durationInMonths - valid - expired - maximallyRedeemed Model157: type: object properties: displayName: type: string invoices_settings: type: object properties: default_payment_method: type: string price: type: object properties: id: type: string required: - id Model158: type: object properties: id: type: string created: type: number price: $ref: '#/definitions/price' required: - id - created - price Model159: type: array items: $ref: '#/definitions/Model158' items: type: object properties: data: $ref: '#/definitions/Model159' required: - data Model160: type: object properties: id: type: string cancel_at: type: number x-alternatives: - type: number - type: string canceled_at: type: number x-alternatives: - type: number - type: string cancel_at_period_end: type: boolean description: >- True if the subscription will not automatically renew at the end of the current billing period. Else false. created: type: number description: This is the date the subscription was created. current_period_end: type: number description: This is the end date of the current billing cycle. current_period_start: type: number description: This is the start date of the current billing cycle. ended_at: type: number x-alternatives: - type: number - type: string items: $ref: '#/definitions/items' latest_invoice: type: string x-alternatives: - type: string - $ref: '#/x-alt-definitions/latest_invoice' status: type: string description: >- The status of the product (e.g. `active`, `canceled`, `trialing`, `unpaid`, etc). required: - id - cancel_at_period_end - created - current_period_end - current_period_start - status Model161: type: array items: $ref: '#/definitions/Model160' Model162: type: object properties: data: $ref: '#/definitions/Model161' required: - data Model163: type: object properties: invoices_settings: $ref: '#/definitions/invoices_settings' subscriptions: $ref: '#/definitions/Model162' Model164: type: object properties: currencyCode: type: string description: The three-letter ISO currency code, in uppercase. x-convert: case: upper required: - currencyCode Model165: type: object properties: token: type: string required: - token Model166: type: object properties: subscriptionId: type: string description: >- A unique identifier for the Stripe [subscription](https://stripe.com/docs/api/subscriptions/object). maxLength: 255 required: - subscriptionId Model167: type: object properties: authPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 authPWVersion2: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKb: type: string description: The new `wrapKb` value as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 wrapKbVersion2: type: string description: The new `wrapKb` value for authPW2 as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 clientSalt: type: string description: >- The salt used when creating authPW. If not provided, it will be assumed that version one of the password encryption scheme was used. pattern: >- ^identity\.mozilla\.com\/picl\/v1\/quickStretch:|^identity\.mozilla\.com\/picl\/v1\/quickStretchV2: sessionToken: type: string description: >- Indicates whether a new `sessionToken` is required, default to `false`. minLength: 64 maxLength: 64 pattern: ^(?:[a-fA-F0-9]{2})+$ required: - authPW - sessionToken Model168: type: object properties: email: type: string description: The primary email for this account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ oldAuthPW: type: string description: The PBKDF2/HKDF-stretched password as a hex string. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 required: - email - oldAuthPW Model169: type: object properties: email: type: string description: Recovery email for the account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ service: type: string description: >- Identifies the relying service the user was interacting with that triggered the password reset. maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ metricsContext: $ref: '#/definitions/metricsContext' required: - email Model170: type: object properties: code: type: string description: The code sent to the user's recovery email. minLength: 32 maxLength: 32 pattern: ^(?:[a-fA-F0-9]{2})+$ accountResetWithRecoveryKey: type: boolean includeRecoveryKeyPrompt: type: boolean required: - code Model171: type: object properties: accountResetToken: type: string Model172: type: object properties: email: type: string description: Recovery email for the account. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ code: type: string pattern: ^[0-9]+$ x-constraint: length: 8 metricsContext: $ref: '#/definitions/metricsContext' required: - email Model173: type: object properties: code: type: string minLength: 6 maxLength: 8 Model174: type: object properties: code: type: string description: The TOTP code to check maxLength: 32 pattern: ^[0-9]+$ service: type: string maxLength: 16 pattern: ^[a-zA-Z0-9\-]*$ metricsContext: $ref: '#/definitions/metricsContext' required: - code Model175: type: object properties: success: type: boolean required: - success Model176: type: object properties: code: type: string pattern: ^[0-9]+$ tokenVerificationId: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 Model177: type: object properties: metricsContext: $ref: '#/definitions/metricsContext' Model178: type: object properties: success: type: boolean required: - success Model179: type: object properties: code: type: string description: The TOTP code to check maxLength: 32 pattern: ^[0-9]+$ metricsContext: $ref: '#/definitions/metricsContext' required: - code Model180: type: object properties: success: type: boolean required: - success Model181: type: object properties: code: type: string minLength: 8 maxLength: 20 pattern: ^[a-zA-Z0-9]*$ Model182: type: object properties: remaining: type: number Model183: type: object properties: email: type: string description: The secondary email address to verify. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ required: - email Model184: type: object properties: email: type: string description: The secondary email address to verify. maxLength: 255 pattern: >- ^(?:[^\u0000-\u001F\u007F\u0080-\u009F\u2028-\u2029\uD800-\uDFFF\uE000-\uF8FF\uFFF9-\uFFFC\uFFFE-\uFFFF])*$ code: type: string description: Time based code to verify secondary email maxLength: 32 pattern: ^[0-9]+$ required: - email - code Model185: type: object properties: code: type: string description: The TOTP code to check maxLength: 32 pattern: ^[0-9]+$ required: - code Model186: type: object properties: success: type: boolean Model187: type: object properties: metricsContext: $ref: '#/definitions/metricsContext' Model188: type: object properties: qrCodeUrl: type: string secret: type: string required: - qrCodeUrl - secret Model189: type: object properties: metricsContext: $ref: '#/definitions/metricsContext' Model190: type: object properties: success: type: boolean required: - success Model191: type: object properties: code: type: string description: The TOTP code to check maxLength: 32 pattern: ^[0-9]+$ metricsContext: $ref: '#/definitions/metricsContext' required: - code Model192: type: object properties: success: type: boolean required: - success Model193: type: object properties: priceId: type: string description: >- A unique identifier for the [price](https://stripe.com/docs/api/prices/object). paymentMethodId: type: string description: >- A unique identifier for the payment method in Stripe; does not apply to IAP subscriptions. maxLength: 30 promotionCode: type: string description: A customer-redeemable code for a coupon. metricsContext: $ref: '#/definitions/metricsContext' required: - priceId Model194: type: object properties: subscription: $ref: '#/definitions/Model160' sourceCountry: type: string x-constraint: length: 2 required: - sourceCountry Model195: type: object properties: priceId: type: string description: >- A unique identifier for the [price](https://stripe.com/docs/api/prices/object). promotionCode: type: string description: A customer-redeemable code for a coupon. token: type: string maxLength: 30 idempotencyKey: type: string description: >- The idempotency key transmitted during the request, if any. For more information, see [Stripe docs](https://stripe.com/docs/error-low-level#idempotency) metricsContext: $ref: '#/definitions/metricsContext' required: - priceId - idempotencyKey Model196: type: object properties: subscription: $ref: '#/definitions/Model160' sourceCountry: type: string x-constraint: length: 2 required: - sourceCountry Model197: type: object properties: signedPayload: type: string required: - signedPayload message: type: object properties: data: type: string required: - data Model198: type: object properties: message: $ref: '#/definitions/message' required: - message Model199: type: object properties: priceId: type: string description: >- A unique identifier for the [price](https://stripe.com/docs/api/prices/object). maxLength: 255 promotionCode: type: string description: A customer-redeemable code for a coupon. required: - priceId Model200: type: object properties: line_items: $ref: '#/definitions/line_items' subtotal: type: number subtotal_excluding_tax: type: number total: type: number total_excluding_tax: type: number tax: $ref: '#/definitions/tax' discount: $ref: '#/definitions/discount' one_time_charge: type: number prorated_amount: type: number required: - line_items - subtotal - subtotal_excluding_tax - total - total_excluding_tax Model201: type: object properties: invoiceId: type: string description: >- A unique identifer for an [invoice](https://stripe.com/docs/api/invoices/object) to Stripe/PayPal customers whose subscriptions are managed by Stripe. paymentMethodId: type: string description: >- A unique identifier for the payment method in Stripe; does not apply to IAP subscriptions. maxLength: 30 idempotencyKey: type: string description: >- The idempotency key transmitted during the request, if any. For more information, see [Stripe docs](https://stripe.com/docs/error-low-level#idempotency) required: - invoiceId - paymentMethodId - idempotencyKey Model202: type: object properties: id: type: string payment_intent: type: string x-alternatives: - type: string - $ref: '#/x-alt-definitions/payment_intent' required: - id Model203: type: object properties: token: type: string maxLength: 30 required: - token Model204: type: object properties: paymentMethodId: type: string description: >- A unique identifier for the payment method in Stripe; does not apply to IAP subscriptions. maxLength: 30 required: - paymentMethodId Model205: type: object properties: client_secret: type: string description: >- The OAuth client secret for the requesting client application. Required for confidential clients, forbidden for public clients. created: type: number description: This is the date the subscription was created. payment_method: type: string x-alternatives: - type: string - $ref: '#/x-alt-definitions/payment_method' source: type: string optional: - source x-alternatives: - type: string - type: string status: type: string description: >- The status of the product (e.g. `active`, `canceled`, `trialing`, `unpaid`, etc). required: - created - status Model206: type: object properties: originalTransactionId: type: string required: - originalTransactionId Model207: type: object properties: sku: type: string token: type: string required: - sku - token Model208: type: object properties: paymentMethodId: type: string description: >- A unique identifier for the payment method in Stripe; does not apply to IAP subscriptions. maxLength: 30 required: - paymentMethodId Model209: type: object properties: id: type: string description: >- A unique identifier for the payment method in Stripe; does not apply to IAP subscriptions. maxLength: 30 required: - id Model210: type: object properties: success: type: boolean Model211: type: object properties: success: type: boolean Model212: type: object properties: planId: type: string description: >- A unique identifier for the [plan](https://stripe.com/docs/api/plans/object). maxLength: 255 required: - planId Model213: type: object properties: subscriptionId: type: string Model214: type: object properties: promotionId: type: string description: The id associated with the promotion code subscriptionId: type: string description: >- A unique identifier for the Stripe [subscription](https://stripe.com/docs/api/subscriptions/object). maxLength: 255 required: - promotionId - subscriptionId x-alt-definitions: grant_type: type: string description: >- The type of grant flow being used. If not specified, it will default to fxa-credentials unless a code parameter is provided, in which case it will default to authorization_code. The value of this parameter determines which other parameters will be expected in the request body, as follows: - When `grant_type=authorization_code`: - `code`: *validators.authorizationCode, required* The authorization code previously obtained through a redirect-based OAuth flow. - `code_verifier`: *validators.pkceCodeVerifier, optional* The [**PKCE**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/fxa-oauth-server/docs/pkce.md) code verifier used when obtaining code. This is required for public OAuth clients, who must authenticate their authorization code use via PKCE. - `redirect_uri`: *string, URI, optional* The URI at which the client received the authorization code. If supplied this must match the value provided during OAuth client registration. - When `grant_type=refresh_token`: - `refresh_token`: *validators.refreshToken, required* A refresh token, as issued by a previous call to this endpoint. - `scope`: *string, optional* A space-separated list of scope values that will be held by the generated token. These must be a subset of the scopes originally granted when the refresh token was generated. - When `grant_type=fxa-credentials`: - `scope`: *string, optional* A space-separated list of scope values that will be held by the generated tokens. - `access_type`: *string, valid(online, offline), optional* If specified, a value of offline will cause the client to be granted a refresh token alongside its access token. -In addition, the request must be authenticated with a sessionToken. default: authorization_code enum: - authorization_code Model1: type: object properties: grant_type: $ref: '#/x-alt-definitions/grant_type' client_id: type: string description: >- The OAuth client identifier for the requesting client application (provided by the connecting client application) pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 client_secret: type: string description: >- The OAuth client secret for the requesting client application. Required for confidential clients, forbidden for public clients. pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 code: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 code_verifier: type: string minLength: 43 maxLength: 128 pattern: ^[A-Za-z0-9-\._~]{43,128}$ redirect_uri: type: string x-format: uri: true ttl: type: number description: >- The desired lifetime of the issued access token, in seconds. The actual lifetime may be smaller than requested depending on server configuration, and will be returned in the `expired_in` property of the response. x-constraint: sign: positive ppid_seed: type: integer description: >- Seed used in `sub` claim generation of JWT access tokens/ID tokens for clients with [Pseudonymous Pairwise Identifiers (PPID)](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/oauth/pairwise-pseudonymous-identifiers.md) enabled. Used to forcibly rotate the `sub` claim. Must be an integer in the range 0-1024. If not specified, it will default to `0`. default: 0 minimum: 0 maximum: 1024 resource: type: string description: >- Indicates the target service or resource at which access is being requested. Its value must be an absolute URI, and may include a query component but must not include a fragment component. Added to the `aud` claim of JWT access tokens. pattern: '#' x-format: uri: true required: - client_id - code Model2: type: string enum: - refresh_token Model3: type: object properties: grant_type: $ref: '#/x-alt-definitions/Model2' client_id: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 client_secret: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 refresh_token: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 scope: type: string ttl: type: number x-constraint: sign: positive ppid_seed: type: integer default: 0 minimum: 0 maximum: 1024 resource: type: string pattern: '#' x-format: uri: true required: - grant_type - client_id - refresh_token Model4: type: string default: fxa-credentials enum: - fxa-credentials access_type: type: string default: online enum: - online - offline reason: type: string enum: - token_migration Model5: type: object properties: grant_type: $ref: '#/x-alt-definitions/Model4' client_id: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 16 scope: type: string access_type: $ref: '#/x-alt-definitions/access_type' ttl: type: number x-constraint: sign: positive resource: type: string pattern: '#' x-format: uri: true reason: $ref: '#/x-alt-definitions/reason' required: - client_id Model6: type: string enum: - urn:ietf:params:oauth:grant-type:token-exchange subject_token_type: type: string enum: - urn:ietf:params:oauth:token-type:refresh_token Model7: type: object properties: grant_type: $ref: '#/x-alt-definitions/Model6' subject_token: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 subject_token_type: $ref: '#/x-alt-definitions/subject_token_type' scope: type: string required: - grant_type - subject_token - subject_token_type - scope token_type: type: string description: >- The type of token, which determines how the client should use it in subsequent requests. Currently only Bearer tokens are supported. enum: - bearer Model8: type: object properties: access_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ refresh_token: type: string description: >- A token that can be used to grant a new access token when the current one expires, via `grant_type=refresh_token` on this endpoint. pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 id_token: type: string description: >- OpenID Connect identity token, provisioned if the authorization was requested with `openid` scope. minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ session_token: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 scope: type: string description: >- A space-separated list of scope values that the user has authorized, or is held by the granted access token that the connecting client will be granted. The requested scope will be provided by the connecting client as part of its authorization request, but may be pruned by the user in a confirmation dialog before being sent to this endpoint. token_type: $ref: '#/x-alt-definitions/token_type' expires_in: type: number description: The number of seconds until the access token will expire. auth_at: type: number description: >- The UTC unix timestamp for the session at which the user last authenticated to FxA server when generating this token, in seconds since the epoch. keys_jwe: type: string maxLength: 1024 pattern: >- ^[A-Za-z0-9-_]+\.[A-Za-z0-9-_]*\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+\.[A-Za-z0-9-_]+$ required: - access_token - scope - token_type - expires_in - auth_at Model9: type: string enum: - bearer Model10: type: object properties: access_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ id_token: type: string minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ scope: type: string token_type: $ref: '#/x-alt-definitions/Model9' expires_in: type: number required: - access_token - scope - token_type - expires_in Model11: type: string enum: - bearer Model12: type: object properties: access_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ refresh_token: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 id_token: type: string minLength: 50 maxLength: 10240 pattern: ^[a-zA-Z0-9_\-\.~=]+$ scope: type: string auth_at: type: number token_type: $ref: '#/x-alt-definitions/Model11' expires_in: type: number required: - access_token - scope - auth_at - token_type - expires_in Model13: type: string enum: - bearer Model14: type: object properties: access_token: type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 x-alternatives: - type: string pattern: ^(?:[0-9a-f]{2})+$ x-constraint: length: 64 - type: string maxLength: 1024 pattern: ^([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)\.([a-zA-Z0-9\-_]+)$ refresh_token: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 64 scope: type: string token_type: $ref: '#/x-alt-definitions/Model13' expires_in: type: number required: - access_token - refresh_token - scope - token_type - expires_in to: type: string description: >- Devices to notify. String `'all'` or an array containing the relevant device ids. enum: - all _endpointAction: type: string enum: - accountVerify excluded: type: array description: >- Array of device ids to exclude from the notification. Ignored unless `to:"all"` is specified. items: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 payload: type: object description: >- Push payload, validated against [**pushpayloads.schema.json**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/lib/pushpayloads.schema.json). Model15: type: object properties: to: $ref: '#/x-alt-definitions/to' _endpointAction: $ref: '#/x-alt-definitions/_endpointAction' excluded: $ref: '#/x-alt-definitions/excluded' payload: $ref: '#/x-alt-definitions/payload' TTL: type: integer description: Push notification TTL, defaults to `0`. minimum: 0 required: - to - payload Model16: type: array items: type: string pattern: ^(?:[a-fA-F0-9]{2})+$ x-constraint: length: 32 Model17: type: object Model18: type: object properties: to: $ref: '#/x-alt-definitions/Model16' _endpointAction: $ref: '#/x-alt-definitions/_endpointAction' payload: $ref: '#/x-alt-definitions/Model17' TTL: type: integer minimum: 0 required: - to - payload payment_method: type: object payment_intent: type: object properties: client_secret: type: string description: >- The OAuth client secret for the requesting client application. Required for confidential clients, forbidden for public clients. created: type: number description: This is the date the subscription was created. payment_method: type: string x-alternatives: - type: string - $ref: '#/x-alt-definitions/payment_method' source: type: string optional: - source x-alternatives: - type: string - type: string status: type: string description: >- The status of the product (e.g. `active`, `canceled`, `trialing`, `unpaid`, etc). required: - created - status latest_invoice: type: object properties: id: type: string payment_intent: type: string x-alternatives: - type: string - $ref: '#/x-alt-definitions/payment_intent' required: - id