sketchxflow-com Auth API

openapi: 3.2.0
info:
  title: SketchXFlow Auth API
  version: 0.1.0
tags:
- name: Auth
paths:
  /auth/register:
    post:
      tags:
      - Auth
      summary: Register
      operationId: register_auth_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/login:
    post:
      tags:
      - Auth
      summary: Login
      operationId: login_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/logout:
    post:
      tags:
      - Auth
      summary: Logout
      operationId: logout_auth_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/me:
    get:
      tags:
      - Auth
      summary: Me
      operationId: me_auth_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    delete:
      tags:
      - Auth
      summary: Delete My Account
      description: 'Permanently delete the requesting user''s account.


        Required body:

        { "confirm_email": "" }


        Optional body:

        { "current_password": "" }


        What happens: services/account_deletion.delete_user_account runs the

        full cascade — projects, backups, components, comments, form

        submissions, generation logs, quality scores, audits, refresh

        tokens, GCS blobs, Firebase Auth user. Billing rows (payments,

        subscriptions, coin_transactions) are anonymised but retained for

        legal/tax obligations. See /terms §2.2 for the user-facing promise.


        On success the response also clears the auth cookies — the session

        is over.'
      operationId: delete_my_account_auth_me_delete
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Auth
      summary: Update Profile
      description: 'Update mutable profile fields: full_name, bio, avatar_url.'
      operationId: update_profile_auth_me_patch
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/session:
    get:
      tags:
      - Auth
      summary: Session
      description: 'The app''s first "who am I?" on load. A browser carrying no session

        cookie at all is a signed-out visitor, which is not an error: 204, so the

        page logs no failed request and makes no pointless /auth/refresh (the 401

        pair was in every signed-out homepage''s console, 2026-10-09). With a

        cookie it is exactly /auth/me — 401 when the access token has expired, so

        the client refreshes.'
      operationId: session_auth_session_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/me/showcase-name:
    patch:
      tags:
      - Auth
      summary: Set Showcase Name
      description: 'The name shown with this person''s designs in the Community and on the

        audit certificates they run. Free-trial guests can set it too; it moves to

        their account when they sign up.'
      operationId: set_showcase_name_auth_me_showcase_name_patch
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/guest:
    post:
      tags:
      - Auth
      summary: Start Guest
      description: 'Start (or resume) a signed-out trial: a guest session that can run

        one free web design (view-only). `fp` is the browser''s device hash.'
      operationId: start_guest_auth_guest_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - additionalProperties: true
                type: object
              - 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'
  /auth/refresh:
    post:
      tags:
      - Auth
      summary: Refresh
      operationId: refresh_auth_refresh_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/me/budget:
    get:
      tags:
      - Auth
      summary: Get My Budget
      description: 'Get the current user''s coin budget status, including live operation

        prices and coin packs. Mirrors /api/me/budget so the frontend can call

        either path. Coin packs and operation costs are sourced from MongoDB

        (platform_config) so admin edits in /admin/economy take effect with no

        code change.


        With a team workspace selected (``x-team-id``) whose plan is live, the

        balance is the user''s seat plus the team''s shared pool — what their next

        generation there would spend (services.team_wallet.scoped_budget).

        ``?scope=personal`` always answers with the personal plan (the Account

        page is the personal account).'
      operationId: get_my_budget_auth_me_budget_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/me/usage:
    get:
      tags:
      - Auth
      summary: Get My Usage
      description: Get the current user's generation usage history (daily breakdown).
      operationId: get_my_usage_auth_me_usage_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/forgot-password:
    post:
      tags:
      - Auth
      summary: Forgot Password
      description: 'Mirror the requesting email into Firebase Auth (lazy create) so the

        frontend''s subsequent `sendPasswordResetEmail()` call has a Firebase

        user to send to.


        We do NOT confirm whether the email exists in our Mongo — returning

        different responses for hit vs miss is a known account-enumeration

        leak. Always 200 OK; the user discovers nothing about who''s

        registered.


        The actual email is sent by Firebase Auth''s client SDK from the

        browser using the project''s email templates. No SMTP setup needed

        on our side. Backend''s job here is just the mirror.'
      operationId: forgot_password_auth_forgot_password_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/sync-password-from-firebase:
    post:
      tags:
      - Auth
      summary: Sync Password From Firebase
      description: 'Bridge handler called by /__/auth/action AFTER Firebase has accepted

        the password reset. We verify the Firebase ID token (cryptographic

        proof the user just authenticated with their new password), then

        update the corresponding Mongo user''s password_hash so email +

        password login through our backend continues to work.


        Body:

        { "id_token": "",

        "new_password": "" }


        Returns: { ok: true } on success. On failure (bad token, account

        disabled, mismatched email), 401 with a detail message.


        Why we accept the plaintext password here even though Firebase has

        it: we hash with bcrypt + a different secret than Firebase, and Mongo

        is the gate for our session JWT minting. Without this sync, users

        would have to keep using Google sign-in or the Firebase reset link

        forever — they couldn''t log in with email + password against our

        backend.'
      operationId: sync_password_from_firebase_auth_sync_password_from_firebase_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/me/avatar:
    post:
      tags:
      - Auth
      summary: Upload Avatar
      description: 'Upload a profile avatar image (multipart/form-data, field: file).

        Returns { avatar_url } pointing at GCS. Max 2 MB, image/* only.'
      operationId: upload_avatar_auth_me_avatar_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/me/password:
    post:
      tags:
      - Auth
      summary: Set Or Change Password
      description: 'Set a first password (passwordless accounts) or change it.


        - Account WITH a password: ``current_password`` is required and checked.

        - Account WITHOUT one (Google sign-in): ``reauth_id_token`` is required —

        a Firebase ID token from a Google sign-in in the last five minutes, for

        the Google identity on this account (see _require_fresh_reauth). The

        session cookie alone is never enough to add a password.

        - Free-trial guests can''t set one: they have no account yet.


        Every attempt counts against a per-account ceiling

        (user_service.take_password_attempt) on top of the per-address limit.

        On success every OTHER session is signed out, and the owner is emailed.'
      operationId: set_or_change_password_auth_me_password_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/ws-token:
    get:
      tags:
      - Auth
      summary: Get Ws Token
      operationId: get_ws_token_auth_ws_token_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/onboarding:
    post:
      tags:
      - Auth
      summary: Complete Onboarding
      description: 'Mark first-run guidance as seen on the ACCOUNT (not the browser).


        No body (the original call, still used by the mobile app): the first-login

        onboarding is done. `{"hint": ""}`: that one inline hint is done — it is

        added to `seen_hints` and never shown again on any device.'
      operationId: complete_onboarding_auth_onboarding_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - additionalProperties: true
                type: object
              - type: 'null'
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/devices:
    post:
      tags:
      - Auth
      summary: Register Device
      description: 'Claim an FCM token for the signed-in user, so shares can reach them.


        Body: { "token": "", "platform": "android" }


        Idempotent — the mobile app calls this on every launch and on every FCM

        token refresh, and both are expected to land on an existing row.'
      operationId: register_device_auth_devices_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/devices/{token}:
    delete:
      tags:
      - Auth
      summary: Unregister Device
      description: 'Release a token on sign-out.


        Deliberately not scoped to the caller: the token identifies a *device*, and

        the point of the call is that this device should stop receiving this user''s

        notifications. Someone else''s token is not a useful thing to delete, and

        holding a token already implies possession of the device.'
      operationId: unregister_device_auth_devices__token__delete
      parameters:
      - name: token
        in: path
        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'
  /auth/google/start:
    get:
      tags:
      - Auth
      summary: Google Start
      description: Kick off the Google OAuth flow. Returns a 302 to Google.
      operationId: google_start_auth_google_start_get
      parameters:
      - name: redirect
        in: query
        required: false
        schema:
          type: string
          default: /projects
          title: Redirect
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/google/callback:
    get:
      tags:
      - Auth
      summary: Google Callback
      description: 'Google redirects here after the user consents. We exchange the code,

        resolve the account, set auth cookies, and bounce to the original

        target.'
      operationId: google_callback_auth_google_callback_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/google/status:
    get:
      tags:
      - Auth
      summary: Google Status
      description: 'Frontend hits this to decide which Google sign-in path to use.


        Two backends are available:

        - `firebase`: the Firebase-mediated path (preferred). Frontend

        does signInWithPopup + POSTs the Firebase ID token to

        /auth/google/firebase-token. Driven by FIREBASE_PUBLISH_*.

        - `redirect`: the legacy GCP-OAuth-credentials redirect dance via

        /auth/google/start. Driven by GOOGLE_OAUTH_*.


        The frontend prefers `firebase` when it''s available and falls back

        to `redirect` when it''s not.'
      operationId: google_status_auth_google_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /auth/google/firebase-token:
    post:
      tags:
      - Auth
      summary: Google Firebase Token
      description: 'Trade a Firebase ID token (issued after a Google popup sign-in) for

        SketchXFlow session cookies.


        Body:

        { "id_token": "", "redirect": "/optional/path" }


        Returns the standard /auth/me-shaped user response. On success, the

        response also sets the `access_token` + `refresh_token` cookies so

        the frontend just needs to navigate.'
      operationId: google_firebase_token_auth_google_firebase_token_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Payload
        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:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    RegisterRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        username:
          anyOf:
          - type: string
          - type: 'null'
          title: Username
        password:
          type: string
          title: Password
        full_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Full Name
      type: object
      required:
      - email
      - password
      title: RegisterRequest
    LoginRequest:
      properties:
        email_or_username:
          type: string
          title: Email Or Username
        password:
          type: string
          title: Password
      type: object
      required:
      - email_or_username
      - password
      title: LoginRequest