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. Please read the online documentation to find out details on how CSRF can be confifgured.

    _Be aware that the current renderer is great! but has some limitations._
    In particular
    it can't represent both form input and JSON input - but all APIs take both. Also
    it currently doesn't render 'examples' correctly.

    You can download the latest spec from: https://github.com/jwag956/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/jwag956/flask-security
  license:
    name: MIT
    url: https://github.com/jwag956/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(cv('LOGIN_USER_TEMPLATE')
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
        302:
          description: Response when already logged in (non-JSON request)
          headers:
            Location:
              schema:
                type: string
                example: redirect(cv('POST_LOGIN_VIEW'))
    post:
      summary: Login to application
      description: Supports both json and form request types. If the caller is already logged in, they are logged out and the new user is logged in.
      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/Login"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/Login"
      responses:
        200:
          description: Login response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
            text/html:
              schema:
                description: Unsuccessful login
                example: render_template(cv('LOGIN_USER_TEMPLATE') with error values
        302:
          description: >
            Success or failure with form data body.
            redirect('next') or redirect(config_value('POST_LOGIN_VIEW'))
          headers:
            Location:
              description: redirect
              schema:
                type: string
                example: redirect(cv('POST_LOGIN_VIEW'))
        400:
          description: Errors while validating login
          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:
                example: render_template(cv('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.
                example: render_template(cv('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
            cv('REDIRECT_BEHAVIOR') == 'spa'.
          headers:
            Location:
              description: |
                On spa-success: cv('POST_LOGIN_VIEW')email={email}

                On spa-error-expired: cv('LOGIN_ERROR_VIEW')?error={msg}&email={email}

                On spa-error-invalid-token: cv('LOGIN_ERROR_VIEW')?error={msg}

                On form-success: cv('POST_LOGIN_VIEW')

                On form-error-expired: cv('LOGIN_VIEW')

                On form-error-invalid-token: cv('LOGIN_VIEW')
              schema:
                type: string
  /logout:
    get:
      summary: Log out current user
      responses:
        302:
          description: Successful logout
          headers:
            Location:
              description: redirect(cv('POST_LOGOUT_VIEW'))
              schema:
                example: redirect(cv('POST_LOGOUT_VIEW'))
    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:
                example: render_template(cv('REGISTER_USER_TEMPLATE')
        302:
          description: Response when already logged in
          headers:
            Location:
              schema:
                type: string
                example: redirect(cv('POST_LOGIN_VIEW'))
    post:
      summary: Register with application
      description: Supports both json and form request types
      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
                example: render_template(cv('REGISTER_USER_TEMPLATE') with error values
        302:
          description: >
            Successful registration with form data body.
          headers:
            Location:
              description: redirect to cv('next') or cv('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(cv('CHANGE_PASSWORD_TEMPLATE'))
    post:
      summary: Change password
      parameters:
        - name: X-CSRF-Token
          in: header
          schema:
            $ref: "#/components/headers/X-CSRF-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.
                example: render_template(cv('CHANGE_PASSWORD_TEMPLATE') with error values
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
        302:
          description: Password has been changed (non-json)
          headers:
            Location:
              description: |
                On success: redirect(cv('POST_CHANGE_VIEW')) or
                            redirect(cv('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:
                example: render_template(cv('FORGOT_PASSWORD_TEMPLATE'))
        302:
          description: Response when already logged in
          headers:
            Location:
              schema:
                type: string
                example: redirect(cv('POST_LOGIN_VIEW'))
    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.
                example: render_template(cv('FORGOT_PASSWORD_TEMPLATE'))
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
        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 cv('REDIRECT_BEHAVIOR') == 'spa' then a 302 is always returned.
      responses:
        200:
          description: Reset password form
          content:
            text/html:
              schema:
                example: render_template(cv('RESET_PASSWORD_TEMPLATE'))
        302:
          description: >
            Redirects depending on success/error and whether
            cv('REDIRECT_BEHAVIOR') == 'spa'.
          headers:
            Location:
              description: |
                On spa-success: cv('RESET_VIEW')?token={token}&email={email}

                On spa-error-expired: cv('RESET_ERROR_VIEW')?error={msg}&email={email}

                On spa-error-invalid-token: cv('RESET_ERROR_VIEW')?error={msg}

                On default-error: redirect(cv('FORGOT_PASSWORD'))
              schema:
                type: string
              examples:
                spa-success:
                  value: cv('RESET_VIEW')?token={token}&email={email}
                spa-error-expired:
                  value: cv('RESET_ERROR_VIEW')?error={msg}&email={email}
                spa-error-invalid-token:
                  value: cv('RESET_ERROR_VIEW')?error={msg}
                default-error:
                  value: redirect(cv('FORGOT_PASSWORD'))
    post:
      summary: Reset password
      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.
                example: render_template(cv('RESET_PASSWORD_TEMPLATE') with error values
            application/json:
              schema:
                $ref: "#/components/schemas/DefaultJsonResponse"
        302:
          description: Password has been reset or validation error (non-json)
          headers:
            Location:
              description: |
                On success: redirect(cv('POST_RESET_VIEW')) or
                    redirect(cv('POST_LOGIN_VIEW'))

                On invalid/expired token: redirect(cv('FORGOT_PASSWORD'))
              schema:
                type: string
              examples:
                success:
                  value: redirect(cv('POST_RESET_VIEW')) or
                    redirect(cv('POST_LOGIN_VIEW'))
                invalid/expired-token:
                  value: redirect(cv('FORGOT_PASSWORD'))
        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(cv('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.
                example: render_template(cv('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.
      responses:
        302:
          description: >
            Redirects depending on success/error and whether
            cv('REDIRECT_BEHAVIOR') == 'spa'.
          headers:
            Location:
              description: |
                On spa-success: cv('POST_CONFIRM_VIEW')?email={email}&{level}={msg} or
                                cv('POST_LOGIN_VIEW')?email={email}&{level}={msg}

                On spa-error-expired: cv('CONFIRM_ERROR_VIEW')?error={msg}&email={email}

                On spa-error-invalid-token: cv('CONFIRM_ERROR_VIEW')?error={msg}

                On form-success: cv('POST_CONFIRM_VIEW') or
                                 cv('POST_LOGIN_VIEW')

                On form-error-expired: cv('CONFIRM_ERROR_VIEW') or
                                       cv('CONFIRM_URL')

                On form-error-invalid-token: cv('CONFIRM_ERROR_VIEW') or
                                             cv('CONFIRM_URL')
              schema:
                type: string

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 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.
    DefaultJsonResponse:
      type: object
      required: [user]
      properties:
        user:
          type: object
          required: [id]
          description: >
            By default just 'id', and 'authentication_token' are returned. However by overriding _User::get_security_payload()_ any attributes of the User model can be returned.
          properties:
            id:
              type: integer
              example: 42
              description: Unique user id (primary key)
            authentication_token:
              type: string
              description: Token to be used in future token-based API calls.
        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
          required: [errors]
          properties:
            errors:
              type: object
              description: Errors per input/form field
              properties:
                email:
                  type: array
                  items:
                    type: string
                    example: Email issues.
                    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 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 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 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.
  headers:
    X-CSRF-Token:
      schema:
        type: string