openapi: 3.0.0
info:
  description: |
    Default API for Flask-Security.

    __N.B. This is preliminary.__

    Since Flask-Security is middleware, with many possible configurations this is a
    guide to how the APIs will behave using standard defaults.

    By default, all POST requests require a CSRF token. This is handled automatically
    if you render the form from your Flask application. If you send JSON, then you must include a request header (configured via __SECURITY_CSRF_HEADER__).
    Please read the online documentation to find out details on how CSRF can be configured.

    You can download the latest spec from: https://github.com/Flask-Middleware/flask-security/blob/master/docs/openapi.yaml
  version: 1.0.0
  title: "Flask-Security External API"
  contact:
    name: Flask-Security-Too
    url: https://github.com/Flask-Middleware/flask-security
  license:
    name: MIT
    url: https://github.com/Flask-Middleware/flask-security/blob/master/LICENSE
paths:
  /login:
    get:
      summary: Retrieve login form and/or user information
      responses:
        200:
          description: >
            Login form or user information. The JSON response will always
            carry the csrf_token information. If the caller is logged in, then
            additional information is returned. This can be very useful for single-page applications where during a force refresh, all state is lost.
            By performing this GET, the session cookie will authenticate the user and the response will contain user information.
          content:
            text/html:
              schema:
                example: render_template(SECURITY_LOGIN_USER_TEMPLATE)
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
        302:
          description: Response when already logged in (non-JSON request)
          headers:
            Location:
              description: Redirect to ``SECURITY_POST_LOGIN_VIEW``
              schema:
                type: string
                format: uri
    post:
      summary: Login to application
      description: Supports both json and form request types. If the caller is already logged in, then in the form case, they are redirected to SECURITY_POST_LOGIN_VIEW, for a json request, a 400 is returned.
      parameters:
        - name: next
          in: query
          description: >
            URL to redirect to on successful login. Ignored for json request.
          schema:
            type: string
        - $ref: "#/components/parameters/include_auth_token"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Login"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/Login"
      responses:
        200:
          description: Login response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginJsonResponse"
            text/html:
              schema:
                description: Unsuccessful login
                type: string
                example: render_template(SECURITY_LOGIN_USER_TEMPLATE) with error values
        302:
          description: >
            If the caller already authenticated, the form contents is ignored and a
            redirect is done: redirect(next) or redirect(SECURITY_POST_LOGIN_VIEW).

            If the caller is NOT already authenticated, and the form contents are
            validated the caller will be redirected to:
            redirect(next) or redirect(SECURITY_POST_LOGIN_VIEW)
          headers:
            Location:
              description: Redirect to ``SECURITY_POST_LOGIN_VIEW``
              schema:
                type: string
        400:
          description: Errors while validating login, or caller already authenticated/logged in.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /login(passwordless):
    get:
      summary: Return passwordless login form
      responses:
        200:
          description: Passwordless login form
          content:
            text/html:
              schema:
                type: string
                example: render_template(SECURITY_SEND_LOGIN_TEMPLATE)
    post:
      summary: Send passwordless login instructions email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailLink"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/EmailLink"
      responses:
        200:
          description: >
            Passwordless login response. For forms both success and validation errors.
          content:
            text/html:
              schema:
                description: Passwordless login form - with errors.
                type: string
                example: render_template(SECURITY_SEND_LOGIN_TEMPLATE)
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
        400:
          description: Errors while validating form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /login(passwordless)/{token}:
    parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Login via token
      description: >
        This is the result of getting a passwordless login token and is usually
        the result of clicking the link from a passwordless email.
        This ALWAYS results in a 302 redirect.
      responses:
        302:
          description: >
            Redirects depending on success/error and whether
            __SECURITY_REDIRECT_BEHAVIOR__ == 'spa'.
          headers:
            Location:
              description: |
                On spa-success: SECURITY_POST_LOGIN_VIEW?identity={identity}&email={email}

                On spa-error-expired: SECURITY_LOGIN_ERROR_VIEW?error={msg}&identity={identity}&email={email}

                On spa-error-invalid-token: SECURITY_LOGIN_ERROR_VIEW?error={msg}

                On form-success: SECURITY_POST_LOGIN_VIEW

                On form-error-expired: SECURITY_LOGIN_VIEW

                On form-error-invalid-token: SECURITY_LOGIN_VIEW
              schema:
                type: string
  /logout:
    get:
      summary: Log out current user
      responses:
        302:
          description: Successful logout
          headers:
            Location:
              description: Redirect to ``SECURITY_POST_LOGOUT_VIEW``
              schema:
                type: string
    post:
      summary: Log out current user
      responses:
        200:
          description: Successful logout
          content:
            application/json:
              schema:
                type: object
                required: [meta]
                properties:
                  meta:
                    type: object
                    required: [code]
                    properties:
                      code:
                        type: integer
                        example: 200
                        description: Http status code
  /register:
    get:
      summary: Return register form
      responses:
        200:
          description: Register form
          content:
            text/html:
              schema:
                type: string
                example: render_template(SECURITY_REGISTER_USER_TEMPLATE)
        302:
          description: Response when already logged in
          headers:
            Location:
              description: Redirect to ``SECURITY_POST_LOGIN_VIEW``
              schema:
                type: string
    post:
      summary: Register new user with application
      parameters:
        - name: next
          in: query
          description: >
            URL to redirect to on successful registration. Ignored for json request.
          schema:
            type: string

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Register"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/RegisterForm"
      responses:
        200:
          description: Register response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
            text/html:
              schema:
                description: Unsuccessful registration
                type: string
                example: render_template(SECURITY_REGISTER_USER_TEMPLATE) with error values
        302:
          description: >
            Successful registration with form data body.
          headers:
            Location:
              description: redirect to ``next`` or ``SECURITY_POST_REGISTER_VIEW``
              schema:
                type: string
        400:
          description: Errors while validating registration form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /change:
    get:
      summary: Return change password form
      responses:
        200:
          description: change password form
          content:
            text/html:
              schema:
                example: render_template(SECURITY_CHANGE_PASSWORD_TEMPLATE)
    post:
      summary: Change password
      parameters:
        - name: X-XSRF-Token
          in: header
          schema:
            $ref: "#/components/headers/X-CSRF-Token"
        - $ref: "#/components/parameters/include_auth_token"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChangePassword"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/ChangePassword"
      responses:
        200:
          description: Change password response.
          content:
            text/html:
              schema:
                description: Change form validation error.
                type: string
                example: render_template(SECURITY_CHANGE_PASSWORD_TEMPLATE) with error values
            application/json:
              schema:
                $ref: "#/components/schemas/JsonResponseWithToken"
        302:
          description: Password has been changed (non-json)
          headers:
            Location:
              description: |
                On success: Redirect to ``SECURITY_POST_CHANGE_VIEW`` or
                            ``SECURITY_POST_LOGIN_VIEW``
              schema:
                type: string
        400:
          description: Errors while validating form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /reset:
    get:
      summary: Return reset password form
      responses:
        200:
          description: Reset password form
          content:
            text/html:
              schema:
                type: string
                example: render_template(SECURITY_FORGOT_PASSWORD_TEMPLATE)
        302:
          description: Response when already logged in
          headers:
            Location:
              description: Redirect to ``SECURITY_POST_LOGIN_VIEW``
              schema:
                type: string
    post:
      summary: Send reset password instructions email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailLink"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/EmailLink"
      responses:
        200:
          description: >
            Reset password response. For forms both success and validation errors.
          content:
            text/html:
              schema:
                description: Forgot password form - with errors.
                type: string
                example: render_template(SECURITY_FORGOT_PASSWORD_TEMPLATE)
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponseNoUser"
        400:
          description: Errors while validating form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /reset/{token}:
    parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Request to reset password
      description: >
        This is the result of getting a reset-password token and is usually
        the result of clicking the link from a reset-password email.
        If __SECURITY_REDIRECT_BEHAVIOR__ == 'spa' then a 302 is always returned.
      responses:
        200:
          description: Reset password form
          content:
            text/html:
              schema:
                type: string
                example: render_template(SECURITY_RESET_PASSWORD_TEMPLATE)
        302:
          description: >
            Redirects depending on success/error and whether
            __SECURITY_REDIRECT_BEHAVIOR__ == 'spa'.
          headers:
            Location:
              description: |
                On spa-success: SECURITY_RESET_VIEW?token={token}&identity={identity}&email={email}

                On spa-error-expired: SECURITY_RESET_ERROR_VIEW?error={msg}&identity={identity}&email={email}

                On spa-error-invalid-token: SECURITY_RESET_ERROR_VIEW?error={msg}

                On default-error: redirect(SECURITY_FORGOT_PASSWORD)
              schema:
                type: string
    post:
      summary: Reset password
      parameters:
        - $ref: "#/components/parameters/include_auth_token"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetPassword"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/ResetPassword"
      responses:
        200:
          description: Reset response
          content:
            text/html:
              schema:
                description: Reset form validation error.
                type: string
                example: render_template(SECURITY_RESET_PASSWORD_TEMPLATE) with error values
            application/json:
              schema:
                $ref: "#/components/schemas/JsonResponseWithToken"
        302:
          description: Password has been reset or validation error (non-json)
          headers:
            Location:
              description: |
                On success: redirect(SECURITY_POST_RESET_VIEW) or
                    redirect(SECURITY_POST_LOGIN_VIEW)

                On invalid/expired token: redirect(SECURITY_FORGOT_PASSWORD)
              schema:
                type: string
        400:
          description: Errors while validating form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /confirm:
    get:
      summary: Return send confirmation form
      responses:
        200:
          description: Confirmation form
          content:
            text/html:
              schema:
                example: render_template(SECURITY_SEND_CONFIRMATION_TEMPLATE)
    post:
      summary: Send confirmation email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailLink"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/EmailLink"
      responses:
        200:
          description: >
            Confirmation response. For forms both success and validation errors.
          content:
            text/html:
              schema:
                description: Confirmation form - with errors.
                type: string
                example: render_template(SECURITY_SEND_CONFIRMATION_TEMPLATE)
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
        400:
          description: Errors while validating form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /confirm/{token}:
    parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Request to confirm account
      description: >
        This is the result of getting a confirmation token and is usually
        the result of clicking the link from a confirmation email.
        This ALWAYS results in a 302 redirect.
        By default (unless __SECURITY_AUTO_LOGIN_AFTER_CONFIRM__ == False), the user
        denoted by the token is logged in as a side-effect.
      responses:
        302:
          description: >
            Redirects depending on success/error and whether
            __SECURITY_REDIRECT_BEHAVIOR__ == 'spa'.
          headers:
            Location:
              description: |
                On spa-success: SECURITY_POST_CONFIRM_VIEW?identity={identity}&email={email}&{level}={msg}

                On spa-error-expired: SECURITY_CONFIRM_ERROR_VIEW?error={msg}&identity={identity}&email={email}

                On spa-error-invalid-token: SECURITY_CONFIRM_ERROR_VIEW?error={msg}

                On form-success: SECURITY_POST_CONFIRM_VIEW or
                                 SECURITY_POST_LOGIN_VIEW

                On form-success (no auto-login): SECURITY_POST_CONFIRM_VIEW or
                                 SECURITY_LOGIN_URL

                On form-error-expired: SECURITY_CONFIRM_ERROR_VIEW or
                                       SECURITY_CONFIRM_URL

                On form-error-invalid-token: SECURITY_CONFIRM_ERROR_VIEW or
                                             SECURITY_CONFIRM_URL
              schema:
                type: string
  /us-signin:
    get:
      summary: Unified Sign In.
      responses:
        200:
          description: Sign in form
          content:
            text/html:
              schema:
                example: render_template(SECURITY_US_SIGNIN_TEMPLATE)
            application/json:
              schema:
                type: object
                properties:
                  available_methods:
                    type: string
                    description: Config setting SECURITY_US_ENABLED_METHODS
                  code_methods:
                    type: string
                    description: All SECURITY_US_ENABLED_METHODS that require a code to be generated and sent.
                  identity_attributes:
                    type: string
                    description: Configuration setting SECURITY_USER_IDENTITY_ATTRIBUTES
    post:
      summary: Unified Sign In.
      parameters:
        - $ref: "#/components/parameters/include_auth_token"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UsSignin"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/UsSignin"
      responses:
        200:
          description: Unified Sign In response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsSigninJsonResponse"
            text/html:
              schema:
                description: Unsuccessful sign in
                type: string
                example: render_template(SECURITY_US_SIGNIN_TEMPLATE) with error values
        302:
          description: >
            If the caller already authenticated, the form contents is ignored and a
            redirect is done: redirect(next) or redirect(SECURITY_POST_LOGIN_VIEW).

            If the caller is NOT already authenticated, and the form contents are
            validated the caller will be redirected to:
            redirect(next) or redirect(SECURITY_POST_LOGIN_VIEW)
          headers:
            Location:
              description: Redirect to ``SECURITY_POST_LOGIN_VIEW``
              schema:
                type: string
        400:
          description: Errors while validating attributes, or caller already authenticated/logged in.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /us-signin/send-code:
    get:
      summary: Unified Sign In send authentication code
      responses:
        200:
          description: Send Code form
          content:
            text/html:
              schema:
                example: render_template(SECURITY_US_SIGNIN_TEMPLATE)
            application/json:
              schema:
                type: object
                properties:
                  methods:
                    type: string
                    description: Config setting SECURITY_US_ENABLED_METHODS
                  code_methods:
                    type: string
                    description: All SECURITY_US_ENABLED_METHODS that require a code to be generated and sent.
                  identity_attributes:
                    type: string
                    description: Configuration setting SECURITY_USER_IDENTITY_ATTRIBUTES
    post:
      summary: Send Code for unified sign in.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UsSigninSendCode"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/UsSigninSendCode"
      responses:
        200:
          description: Send code response
          content:
            application/json:
              schema:
                description: Code successfully sent
            text/html:
              schema:
                description: Validation error, code send error, or code successfully sent
                type: string
                example: render_template(SECURITY_US_SIGNIN_TEMPLATE) with error values
        400:
          description: Errors while validating attributes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
        500:
          description: Error when trying to send code.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"

  /us-verify:
    get:
      summary: Unified sign in re-authentication.
      description: >
        If an endpoint is protected with @auth_required() with a freshness declaration
        this endpoint will be called to request an already signed in user to re-authenticate.
      responses:
        200:
          description: Verify/re-authenticate form
          content:
            text/html:
              schema:
                example: render_template(SECURITY_US_VERIFY_TEMPLATE)
            application/json:
              schema:
                type: object
                properties:
                  available_methods:
                    type: string
                    description: Config setting SECURITY_US_ENABLED_METHODS
                  code_methods:
                    type: string
                    description: All SECURITY_US_ENABLED_METHODS that require a code to be generated and sent.
    post:
      summary: Unified sign in re-authentication
      parameters:
        - $ref: "#/components/parameters/include_auth_token"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UsSigninVerify"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/UsSigninVerify"
      responses:
        200:
          description: Verify/re-authenticate response.
          content:
            application/json:
              schema:
                allOf:
                  - description: >
                      The user successfully re-authenticated.
                  - $ref: "#/components/schemas/JsonResponseWithToken"
            text/html:
              schema:
                description: Unsuccessful re-authentication.
                type: string
                example: render_template(SECURITY_US_VERIFY_TEMPLATE) with error values
        302:
          description: User successfully re-authenticated when using form based request.
          headers:
            Location:
              description: Redirect to ``next`` or ``SECURITY_POST_VERIFY_VIEW``
              schema:
                type: string
        400:
          description: Errors while validating attributes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /us-verify/send-code:
    get:
      summary: Unified sign in verify/re-authenticate send authentication code
      responses:
        200:
          description: Send Code form
          content:
            text/html:
              schema:
                example: render_template(SECURITY_US_VERIFY_TEMPLATE)
            application/json:
              schema:
                type: object
                properties:
                  methods:
                    type: string
                    description: Config setting SECURITY_US_ENABLED_METHODS
                  code_methods:
                    type: string
                    description: All SECURITY_US_ENABLED_METHODS that require a code to be generated and sent.
    post:
      summary: Send Code for unified sign in verify.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UsSigninVerifySendCode"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/UsSigninVerifySendCode"
      responses:
        200:
          description: Send code response
          content:
            application/json:
              schema:
                description: Code successfully sent
            text/html:
              schema:
                description: Validation error, code send error, or code successfully sent
                type: string
                example: render_template(SECURITY_US_VERIFY_TEMPLATE) with error values
        400:
          description: Errors while validating attributes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
        500:
          description: Error when trying to send code.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /us-setup:
    get:
      summary: Unified sign in setup passcode options.
      responses:
        200:
          description: Setup form
          content:
            text/html:
              schema:
                example: render_template(SECURITY_US_SETUP_TEMPLATE)
            application/json:
              schema:
                type: object
                properties:
                  available_methods:
                    type: string
                    description: Config setting SECURITY_US_ENABLED_METHODS
                  active_methods:
                    type: string
                    description: Methods that have already been setup.
                  setup_methods:
                    type: string
                    description: All SECURITY_US_ENABLED_METHODS that require setup.
                  identity_attributes:
                    type: string
                    description: Configuration setting SECURITY_USER_IDENTITY_ATTRIBUTES
                  phone:
                    type: string
                    description: existing configured phone number
    post:
      summary: Unified sign in setup.
      description: >
        An authenticated user can call this endpoint to update or add additional methods for authenticating (e.g. sms, authenticator app). This is controlled by application configuration settings SECURITY_US_ENABLED_METHODS. This endpoint is protected by a 'freshness' check - meaning the caller will be required to have authenticated recently. In addition, to ensure correctness, the newly setup method must be verified by sending and entering a code prior to it being permanently stored. This verification process is also time-limited.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UsSetup"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/UsSetup"
      responses:
        200:
          description: Unified sign in setup response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsSetupJsonResponse"
            text/html:
              schema:
                description: Invalid form values or verification code sent successfully and should be entered into the form.
                type: string
                example: render_template(SECURITY_US_SETUP_TEMPLATE) with error values
        400:
          description: Errors while validating attributes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
        500:
          description: Error when trying to send code.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /us-setup/{token}:
    parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
    get:
      summary: Validate unified sign in setup request.
      description: >
        This does nothing but redirect back to the setup form.
      responses:
        200:
          description: Get form.
          content:
            text/html:
              schema:
                example: render_template(SECURITY_US_SETUP_TEMPLATE)

    post:
      summary: Validate passcode sent and store setup method.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UsSetupValidateRequest"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/UsSetupValidateRequest"
      responses:
        200:
          description: Successfully validated and persisted sign in method.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsSetupValidateJsonResponse"
        302:
          description: Successfuly validated and persisted sign in method.
          headers:
            Location:
              description: |
                On form-success: SECURITY_POST_SETUP_VIEW or
                                 SECURITY_POST_LOGIN_VIEW
              schema:
                type: string
        400:
          description: Validation failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /us-verify-link:
    parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
      - name: code
        in: query
        required: true
        schema:
          type: string
    get:
      summary: A magic link to authenticate (instead of manually entering a code).
      description: >
        This is the result of getting a passcode link and is usually
        the result of clicking the link from an email.
        This ALWAYS results in a 302 redirect.
        N.B. Magic link with 2FA enabled does not work and the SPA will get a redirect to the login error page with tf_required. Must use code option instead.
      responses:
        302:
          description: >
            Redirects depending on success/error and whether
            __SECURITY_REDIRECT_BEHAVIOR__ == 'spa'. Also, if Two-Factor authentication has been enabled, further authentication/redirects might be required.
          headers:
            Location:
              description: |
                On spa-success: SECURITY_POST_LOGIN_VIEW?identity={identity}&email={email}

                On spa-error-expired: SECURITY_LOGIN_ERROR_VIEW?error={msg}

                On spa-error-invalid-token: SECURITY_LOGIN_ERROR_VIEW?error={msg}

                On spa-two-factor-required: SECURITY_LOGIN_ERROR_VIEW?tf_required=1

                On form-success: SECURITY_POST_LOGIN_VIEW

                On form-error-expired: SECURITY_US_SIGNIN_URL

                On form-error-invalid-token: SECURITY_US_SIGNIN_URL

                On form-success and two-factor: SECURITY_TWO_FACTOR_TOKEN_VALIDATION_URL or SECURITY_TWO_FACTOR_SETUP_URL
              schema:
                type: string

  /tf-setup:
    get:
      summary: Two-factor authentication setup.
      responses:
        200:
          description: Setup form
          content:
            text/html:
              schema:
                example: render_template(SECURITY_TWO_FACTOR_SETUP_TEMPLATE)
            application/json:
              schema:
                type: object
                properties:
                  tf_required:
                    type: string
                    description: Config setting SECURITY_TWO_FACTOR_REQUIRED.
                  tf_primary_method:
                    type: string
                    description: Current (if any) setup method.
                  tf_available_methods:
                    type: string
                    description: Config setting SECURITY_TWO_FACTOR_ENABLED_METHODS. If SECURITY_TWO_FACTOR_REQUIRED is false then 'disable' will be part of the set.
                  tf_phone_number:
                    type: string
                    description: Currently configured (if any) phone number.
    post:
      summary: Two factor setup.
      description: >
        Two-factor setup can be used in three cases:

        1) Initial login and application requires 2FA

        2) An authenticated user wishing to change their 2FA configuration

        3) An authenticated user wishes to enable or disable 2FA (assuming SECURITY_TWO_FACTOR_REQUIRED is False).


        Allowed 2FA methods are controlled via the configuration SECURITY_TWO_FACTOR_ENABLED_METHODS.


        This endpoint is protected by a 'freshness' check - meaning the caller will be required to have authenticated recently. In addition, to ensure correctness, the newly setup method must be verified by sending and entering a code prior to it being permanently stored.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TfSetup"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/TfSetup"
      responses:
        200:
          description: >
            Two factor setup response. Please note that the newly setup method must be validated PRIOR to it being stored permanently.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TfSetupJsonResponse"
            text/html:
              schema:
                description: Invalid form values or verification code sent successfully and should be entered into the form.
                type: string
                example: render_template(SECURITY_TWO_FACTOR_SETUP_TEMPLATE) with error values
        400:
          description: Errors while validating attributes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
        500:
          description: Error when trying to send code.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"
  /tf-validate:
    get:
      summary: Retrieve form based on current two-factor state.
      responses:
        200:
          description: Code validation
          content:
            text/html:
              schema:
                description: >
                  If this is a normal, already setup method, then render_template(SECURITY_TWO_FACTOR_VERIFY_CODE_TEMPLATE) is returned;
                  if this is validating a new method then render_template(SECURITY_TWO_FACTOR_SETUP_TEMPLATE) is returned.
                type: string
    post:
      summary: Send two-factor code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  description: The code sent via the configured method (e.g. SMS, email, authenticator).
                  type: string
                  example: 12345
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                code:
                  description: The code sent via the configured method (e.g. SMS, email, authenticator).
                  type: string
                  example: 12345
      responses:
        200:
          description: Two factor code validation response.
          content:
            application/json:
              schema:
                allOf:
                  - description: >
                      The code was correct, the caller is now signed in.
                  - $ref: "#/components/schemas/TfValidateJsonResponse"
            text/html:
              schema:
                description:
                  Unsuccessfully processed code. As above, which form is
                  rendered depends on the state of the user's two factor configuration.
                type: string
        302:
          description: User successfully sent code when using form based request. The caller is not logged in.
          headers:
            Location:
              description: Redirect to either ``next`` or ``SECURITY_POST_LOGIN_VIEW``
              schema:
                type: string
        400:
          description: Errors while validating attributes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"

  /tf-rescue:
    get:
      summary: Help user that has lost authenticator or SMS device.
      responses:
        200:
          description: Return form.
          content:
            text/html:
              schema:
                description: >
                  render_template(SECURITY_TWO_FACTOR_VERIFY_CODE_TEMPLATE).
                type: string
    post:
      summary: Request help.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                help-setup:
                  description: Either 'lost_device' or 'no_mail_access'.
                  type: string
                  example: "lost_device"
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                help_setup:
                  description: Either 'lost_device' or 'no_mail_access'.
                  type: string
                  example: "lost_device"
      responses:
        200:
          description: >
            If 'lost_device' was specified, then an authentication code was sent to the email
            on record for the user. If 'no_mail_access' then an email was sent to administrator address
            specified by SECURITY_TWO_FACTOR_RESCUE_MAIL.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponseNoUser"
            text/html:
              schema:
                description: Invalid form values or verification code sent successfully and should be entered into the form.
                type: string
                example: render_template(SECURITY_TWO_FACTOR_VERIFY_CODE_TEMPLATE) with error values
        400:
          description: Failed to send code
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonErrorResponse"

components:
  schemas:
    Login:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          description: |
            user identifier. This is by default an email address, but can be any (unique)
            field that is part of the User model and is defined in the __SECURITY_USER_IDENTITY_ATTRIBUTES__ configuration variable. It will also match against numeric User model fields.
        password:
          type: string
          description: Password
        remember_me:
          type: boolean
          description: >
            If true, will remember userid as part of cookie. There is a configuration variable DEFAULT_REMEMBER_ME that can be set. This field will override that.
        tf_validity_token:
          type: string
          description: Code verifying the user has successfully verfied 2FA in the past. If verified, the user is able to skip validation of the second factor. Only used when SECURITY_TWO_FACTOR_ALWAYS_VALIDATE is False.
    LoginJsonResponse:
      type: object
      description: >
        The user successfully signed in. Note that depending on SECURITY_TWO_FACTOR configuration variables, a second form of authentication might be required.
        Note that if 2FA is not configured, none of the ``tf_`` properties will be returned.
      required: [meta, response]
      properties:
        meta:
          type: object
          required: [code]
          properties:
            code:
              type: integer
              example: 200
              description: Http status code
        response:
          type: object
          properties:
            authentication_token:
              type: string
              description: >
                Token to be used in future token-based API calls. Only returned if "include_auth_token" parameter is set.
            tf_required:
              type: boolean
              description: If two-factor authentication is required for caller.
            tf_state:
              type: string
              description: if "setup_from_login" then the caller must go through two-factor setup endpoint. If "ready" then a code has been sent and should be supplied to SECURITY_TWO_FACTOR_TOKEN_VALIDATION_URL.
            tf_primary_method:
              type: string
              description: Which method was used to send code.
    DefaultJsonResponse:
      type: object
      properties:
        user:
          type: object
          description: >
            By default an empty dictionary is returned. However by overriding _User::get_security_payload()_ any attributes of the User model can be returned.
        csrf_token:
          type: string
          description: Session CSRF token
    DefaultJsonResponseNoUser:
      type: object
      properties:
        csrf_token:
          type: string
          description: Session CSRF token
    JsonResponseWithToken:
      type: object
      properties:
        user:
          type: object
          description: >
            By default an empty dictionary is returned. However by overriding _User::get_security_payload()_ any attributes of the User model can be returned.
          properties:
            authentication_token:
              type: string
              description: >
                Token to be used in future token-based API calls.
                Note this only returned from those APIs that accept a
                'include_auth_token' query param.
        csrf_token:
          type: string
          description: Session CSRF token
    DefaultJsonErrorResponse:
      type: object
      required: [meta, response]
      properties:
        meta:
          type: object
          required: [code]
          properties:
            code:
              type: integer
              example: 400
              description: Http status code
        response:
          type: object
          description: >
            For form validation errors, the 'errors' key will be set with a list of errors per
            invalid form input field. For non-form related errors, the 'error' key will be set
            with a single (localized) error string.
          properties:
            errors:
              type: object
              description: >
                Errors per input/form field ('email' below is just an example)
              properties:
                email:
                  type: array
                  items:
                    type: string
                    example: Email issues.
                    description: Error message (localized)
            error:
              type: string
              example: "Unauthenticated"
              description: Error message (localized)
    Register:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          description: >
            user identifier. This is by default an email address, but can be any (unique)
            field that is part of the User model and is defined in the __SECURITY_USER_IDENTITY_ATTRIBUTES__ configuration variable. It will also match against numeric User model fields.
        password:
          type: string
          description: Password
    RegisterForm:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          description: >
            user identifier. This is by default an email address, but can be any (unique)
            field that is part of the User model and is defined in the __SECURITY_USER_IDENTITY_ATTRIBUTES__ configuration variable. It will also match against numeric User model fields.
        password:
          type: string
          description: Password
        password_confirm:
          type: string
          description: >
            If present, must re-type in password. This will not be present if the __SECURITY_CONFIRM__ configuration is true.
        next:
          type: string
          description: >
            Redirect URL. Overrides __SECURITY_POST_REGISTER_VIEW__.
    ResetPassword:
      type: object
      required: [password, password_confirm]
      properties:
        password:
          type: string
          description: Password
        password_confirm:
          type: string
          description: Password - again
    ChangePassword:
      type: object
      required: [password, new_password, new_password_confirm]
      properties:
        password:
          type: string
          description: Password
        new_password:
          type: string
          description: New password
        new_password_confirm:
          type: string
          description: New password - again
    EmailLink:
      type: object
      required: [email]
      properties:
        email:
          type: string
          description: >
            Email address to send link email to.
    UsSignin:
      type: object
      required: [identity, passcode]
      properties:
        identity:
          type: string
          description: Configured by SECURITY_USER_IDENTITY_ATTRIBUTES
          example: me@you.com, +16505551212
        passcode:
          type: string
          description: password or code
        remember_me:
          type: boolean
        tf_validity_token:
          type: string
          description: Code verifying the user has successfully verfied 2FA in the past. If verified, the user is able to skip validation of the second factor. Only used when SECURITY_TWO_FACTOR_ALWAYS_VALIDATE is False.
    UsSigninJsonResponse:
      type: object
      description: >
        The user successfully signed in. Note that depending on SECURITY_TWO_FACTOR and SECURITY_US_MFA_REQUIRED configuration variables, a second form of authentication might be required.
      required: [meta, response]
      properties:
        meta:
          type: object
          required: [code]
          properties:
            code:
              type: integer
              example: 200
              description: Http status code
        response:
          type: object
          properties:
            authentication_token:
              type: string
              description: >
                Token to be used in future token-based API calls. Only returned if "include_auth_token" parameter is set.
            tf_required:
              type: boolean
              description: If two-factor authentication is required for caller.
            tf_state:
              type: string
              description: if "setup_from_login" then the caller must go through two-factor setup endpoint. If "ready" then a code has been sent and should be supplied to SECURITY_TWO_FACTOR_TOKEN_VALIDATION_URL.
            tf_primary_method:
              type: string
              description: Which method was used to send code.
    UsSigninSendCode:
      type: object
      required: [identity, chosen_method]
      properties:
        identity:
          type: string
          description: Configured by SECURITY_USER_IDENTITY_ATTRIBUTES
          example: me@you.com, +16505551212
        chosen_method:
          type: string
          description: which method should be used to send the code, as configured with SECURITY_US_ENABLED_METHODS
    UsSigninVerify:
      type: object
      required: [passcode]
      properties:
        passcode:
          type: string
          description: password or code
    UsSigninVerifySendCode:
      type: object
      required: [chosen_method]
      properties:
        chosen_method:
          type: string
          description: which method should be used to send the code, as configured with SECURITY_US_ENABLED_METHODS
    UsSetup:
      type: object
      required: [chosen_method]
      properties:
        chosen_method:
          type: string
          description: which method should be used to send the code, as configured with SECURITY_US_ENABLED_METHODS
        phone:
          type: string
          description: phone number (this will be normalized). Required if chosen_method == "sms".
    UsSetupJsonResponse:
      type: object
      required: [meta, response]
      properties:
        meta:
          type: object
          required: [code]
          properties:
            code:
              type: integer
              example: 200
              description: Http status code
        response:
          type: object
          properties:
            chosen_method:
              type: string
              description: The chosen_method as passed into API.
            phone:
              type: string
              description: The canonicalized phone number if setting up SMS
            authr_key:
              type: string
              description: TOTP key for setting up authenticator (if chosen_method == 'authenticator')
            authr_issuer:
              type: string
              description: Issuer as configured with TOTP_ISSUER (same as used in QRcode) (if chosen_method == 'authenticator')
            authr_username:
              type: string
              description: Username (same as used in QRcode) (if chosen_method == 'authenticator')
            state:
              type: string
              description: Opaque blob that must be pass to /us-setup/<state>. This is a signed, timed token.
    UsSetupValidateRequest:
      type: object
      required: [passcode]
      properties:
        passcode:
          type: string
          description: Code/Passcode as received from method being setup.
    UsSetupValidateJsonResponse:
      type: object
      required: [meta, response]
      properties:
        meta:
          type: object
          required: [code]
          properties:
            code:
              type: integer
              example: 200
              description: Http status code
        response:
          type: object
          properties:
            chosen_method:
              type: string
              description: The chosen_method as passed into API.
            phone:
              type: string
              description: Phone number if set.
    TfSetup:
      type: object
      required: [setup]
      properties:
        setup:
          type: string
          description: >
            Which method should be used to send the code, as configured with SECURITY_TWO_FACTOR_ENABLED_METHODS.
            If SECURITY_TWO_FACTOR_REQUIRED is False, the additional method 'disable' is available.
          example: sms
        phone:
          type: string
          description: phone number (this will be validated for format). Required if setup == "sms".
          example: 650-555-1212
    TfSetupJsonResponse:
      type: object
      required: [meta, response]
      properties:
        meta:
          type: object
          required: [code]
          properties:
            code:
              type: integer
              example: 200
              description: Http status code
        response:
          type: object
          properties:
            tf_state:
              type: string
              description: >
                Current state of Two Factor configuration. Not present when disabling 2FA. This will be set to 'validating_profile'
                indicating the caller needs to call '/tf-validate' with the correct code.
              example: validating_profile
            tf_primary_method:
              type: string
              description: Current method being congfigured.
              example: sms
            tf_authr_key:
              type: string
              description: TOTP key for setting up authenticator (if tf_primary_method == 'authenticator')
            tf_authr_issuer:
              type: string
              description: Issuer as configured with TOTP_ISSUER (same as used in QRcode) (if tf_primary_method == 'authenticator')
            tf_authr_username:
              type: string
              description: Username (same as used in QRcode) (if tf_primary_method == 'authenticator')
    TfValidateJsonResponse:
      type: object
      properties:
        user:
          type: object
          description: >
            By default an empty dictionary is returned. However by overriding _User::get_security_payload()_ any attributes of the User model can be returned.
        csrf_token:
          type: string
          description: Session CSRF token
        tf_validity_token:
          type: string
          description: A timed token that verifies that the user has successfully completed 2FA. Only sent if SECURITY_TWO_FACTOR_ALWAYS_VALIDATE is False and remember_me (from /login POST) is True

  headers:
    X-CSRF-Token:
      description: CSRF token
      schema:
        type: string
  parameters:
    include_auth_token:
      name: include_auth_token
      description: If set/sent, will return an Authentication Token for user
      in: query
      schema:
        type: string