Eshway Auth API

openapi: 3.2.0
info:
  title: Fast Auth API
  version: 0.1.0
tags:
- name: Auth
paths:
  /v1/auth/login:
    post:
      tags:
      - Auth
      summary: Login
      operationId: login_v1_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/register:
    post:
      tags:
      - Auth
      summary: Register
      operationId: register_v1_auth_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/refresh-token:
    post:
      tags:
      - Auth
      summary: Refresh Token
      operationId: refresh_token_v1_auth_refresh_token_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/RefreshTokenRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/forgot-password:
    post:
      tags:
      - Auth
      summary: Forgot Password
      description: 'Send a password-reset email. Always returns the same generic 200

        so unauthenticated callers cannot use this endpoint to enumerate

        accounts. SMTP runs in a BackgroundTask — sending it inline would

        block the async event loop for the duration of the SMTP handshake

        (with retries, up to ~90s under packet loss).'
      operationId: forgot_password_v1_auth_forgot_password_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/auth/reset-password:
    post:
      tags:
      - Auth
      summary: Reset Password
      operationId: reset_password_v1_auth_reset_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/verify-email:
    post:
      tags:
      - Auth
      summary: Verify Email
      operationId: verify_email_v1_auth_verify_email_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/logout:
    post:
      tags:
      - Auth
      summary: Logout
      operationId: logout_v1_auth_logout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogoutRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/enable-2fa:
    post:
      tags:
      - Auth
      summary: Enable 2Fa
      operationId: enable_2fa_v1_auth_enable_2fa_post
      security:
      - OAuth2PasswordBearer: []
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
          title: Email
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/login/verify-otp:
    post:
      tags:
      - Auth
      summary: Verify Otp
      description: 'Complete a 2FA login by presenting the password-verified challenge.


        The previous endpoint accepted (email, otp) only — a valid TOTP alone

        could mint a session, bypassing the password check. We now require a

        challenge_token minted at /login after the password verified, look it

        up to bind to a user_id, verify is_active + OTP, then consume the

        challenge ONLY on success. A single mistyped OTP no longer burns the

        challenge; the failed-attempt counter caps brute force at

        MAX_LOGIN_CHALLENGE_ATTEMPTS per challenge.'
      operationId: verify_otp_v1_auth_login_verify_otp_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyOtpSchema'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/validate-token:
    post:
      tags:
      - Auth
      summary: Validate Token
      description: 'Validate the caller''s JWT.


        Token must arrive in the standard ``Authorization: Bearer ...`` header.

        The previous GET form took the token as a ``?token=`` query parameter,

        which leaked live access tokens into reverse-proxy access logs, browser

        history, and Referer headers (PRE_LAUNCH HIGH-AUTH).'
      operationId: validate_token_v1_auth_validate_token_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/auth/verification-status:
    get:
      tags:
      - Auth
      summary: Check Verification Status
      description: 'Check if a user''s email is verified.


        Returns ``is_verified`` only — the previous response echoed the canonical

        ``email`` from the DB row when one existed and the user-provided string

        otherwise, which let an unauthenticated caller probe registered emails

        by comparing the echoed casing. Rate-limited to 10/minute per IP because

        even a same-shape response can be enumerated at scale.'
      operationId: check_verification_status_v1_auth_verification_status_get
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
          title: Email
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/validate-reset-token:
    get:
      tags:
      - Auth
      summary: Validate Reset Token Endpoint
      description: 'Validate a password-reset token without revealing the linked email.


        The previous response shape included ``email`` so the front-end could

        pre-populate the reset form. That leaked the bound email address to

        anyone who got hold of the token (referrer headers, server logs,

        sharing the link). The reset page should fetch the email through an

        authenticated channel after the user submits, or simply not show it.


        B-4: also reject blacklisted (already-used) jtis so an already-redeemed

        reset link reports invalid here too — matching the behaviour of the

        /reset-password endpoint.'
      operationId: validate_reset_token_endpoint_v1_auth_validate_reset_token_get
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/auth/resend-verification-email:
    post:
      tags:
      - Auth
      summary: Resend Verification Email
      description: 'Resend the email-verification link.


        Always returns the same generic 200 response — even when the email is

        not registered, or when the user is already verified — so this endpoint

        cannot be used to enumerate which emails have accounts. Side effects

        are gated server-side: only unverified users actually receive an email.


        SMTP is dispatched via ``BackgroundTasks`` so the request returns

        immediately rather than blocking the event loop on the SMTP round-trip

        (which has 3 retries x 30s = up to 90s).'
      operationId: resend_verification_email_v1_auth_resend_verification_email_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/auth/google-signin:
    post:
      tags:
      - Auth
      summary: Google Signin
      operationId: google_signin_v1_auth_google_signin_post
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: Token
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RegisterSchema:
      properties:
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          title: Password
        full_name:
          type: string
          title: Full Name
        username:
          type: string
          title: Username
        referral_code:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Referral Code
      type: object
      required:
      - email
      - password
      - full_name
      - username
      title: RegisterSchema
    LoginSchema:
      properties:
        email:
          type: string
          title: Email
        password:
          type: string
          title: Password
      type: object
      required:
      - email
      - password
      title: LoginSchema
    VerifyOtpSchema:
      properties:
        challenge_token:
          type: string
          title: Challenge Token
        otp:
          type: string
          title: Otp
      type: object
      required:
      - challenge_token
      - otp
      title: VerifyOtpSchema
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResetPasswordSchema:
      properties:
        token:
          type: string
          title: Token
        new_password:
          type: string
          title: New Password
      type: object
      required:
      - token
      - new_password
      title: ResetPasswordSchema
    VerifyEmailSchema:
      properties:
        token:
          type: string
          title: Token
      type: object
      required:
      - token
      title: VerifyEmailSchema
    RefreshTokenRequest:
      properties:
        refresh_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Refresh Token
      type: object
      title: RefreshTokenRequest
    LogoutRequest:
      properties:
        refresh_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Refresh Token
      type: object
      title: LogoutRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: token