insforge 1.2.10 → 1.4.8

package/openapi/auth.yaml

@@ -1,1244 +1,1324 @@
-openapi: 3.0.3
-info:
-  title: Insforge Authentication API
-  version: 2.0.0
-  description: Authentication endpoints with separated auth and profile tables
-
-paths:
-  /api/auth/public-config:
-    get:
-      summary: Get public authentication configuration
-      description: Get all public authentication configuration including OAuth providers and email auth settings (public endpoint)
-      tags:
-        - Client
-      responses:
-        '200':
-          description: Public authentication configuration
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  oAuthProviders:
-                    type: array
-                    items:
-                      type: object
-                      properties:
-                        provider:
-                          type: string
-                          enum: [google, github, discord, linkedin, facebook, microsoft]
-                        useSharedKey:
-                          type: boolean
-                  requireEmailVerification:
-                    type: boolean
-                  passwordMinLength:
-                    type: integer
-                    minimum: 4
-                    maximum: 128
-                  requireNumber:
-                    type: boolean
-                  requireLowercase:
-                    type: boolean
-                  requireUppercase:
-                    type: boolean
-                  requireSpecialChar:
-                    type: boolean
-                  verifyEmailRedirectTo:
-                    type: string
-                    nullable: true
-                    description: URL to redirect users after successful email verification (if not set, shows default success page)
-                  resetPasswordRedirectTo:
-                    type: string
-                    nullable: true
-                    description: URL to redirect users after successful password reset (if not set, shows default success page)
-                  verifyEmailMethod:
-                    type: string
-                    enum: [code, link]
-                    description: Method for email verification (code = 6-digit OTP, link = magic link)
-                  resetPasswordMethod:
-                    type: string
-                    enum: [code, link]
-                    description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
-
-  /api/auth/config:
-    get:
-      summary: Get authentication configuration
-      description: Get current authentication settings including all configuration options (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      responses:
-        '200':
-          description: Authentication configuration
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  id:
-                    type: string
-                    format: uuid
-                  requireEmailVerification:
-                    type: boolean
-                  passwordMinLength:
-                    type: integer
-                    minimum: 4
-                    maximum: 128
-                  requireNumber:
-                    type: boolean
-                  requireLowercase:
-                    type: boolean
-                  requireUppercase:
-                    type: boolean
-                  requireSpecialChar:
-                    type: boolean
-                  verifyEmailRedirectTo:
-                    type: string
-                    nullable: true
-                    description: URL to redirect users after successful email verification (if not set, shows default success page)
-                  resetPasswordRedirectTo:
-                    type: string
-                    nullable: true
-                    description: URL to redirect users after successful password reset (if not set, shows default success page)
-                  verifyEmailMethod:
-                    type: string
-                    enum: [code, link]
-                    description: Method for email verification (code = 6-digit OTP, link = magic link)
-                  resetPasswordMethod:
-                    type: string
-                    enum: [code, link]
-                    description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
-                  signInRedirectTo:
-                    type: string
-                    nullable: true
-                    description: URL to redirect users after successful sign in
-                  createdAt:
-                    type: string
-                    format: date-time
-                  updatedAt:
-                    type: string
-                    format: date-time
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-
-    put:
-      summary: Update authentication configuration
-      description: Update authentication settings (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                requireEmailVerification:
-                  type: boolean
-                passwordMinLength:
-                  type: integer
-                  minimum: 4
-                  maximum: 128
-                requireNumber:
-                  type: boolean
-                requireLowercase:
-                  type: boolean
-                requireUppercase:
-                  type: boolean
-                requireSpecialChar:
-                  type: boolean
-                verifyEmailRedirectTo:
-                  type: string
-                  nullable: true
-                  description: URL to redirect users after successful email verification (if not set, shows default success page)
-                resetPasswordRedirectTo:
-                  type: string
-                  nullable: true
-                  description: URL to redirect users after successful password reset (if not set, shows default success page)
-                verifyEmailMethod:
-                  type: string
-                  enum: [code, link]
-                  description: Method for email verification (code = 6-digit OTP, link = magic link)
-                resetPasswordMethod:
-                  type: string
-                  enum: [code, link]
-                  description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
-                signInRedirectTo:
-                  type: string
-                  nullable: true
-                  description: URL to redirect users after successful sign in
-      responses:
-        '200':
-          description: Configuration updated successfully
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  id:
-                    type: string
-                    format: uuid
-                  requireEmailVerification:
-                    type: boolean
-                  passwordMinLength:
-                    type: integer
-                    minimum: 4
-                    maximum: 128
-                  requireNumber:
-                    type: boolean
-                  requireLowercase:
-                    type: boolean
-                  requireUppercase:
-                    type: boolean
-                  requireSpecialChar:
-                    type: boolean
-                  verifyEmailRedirectTo:
-                    type: string
-                    nullable: true
-                    description: URL to redirect users after successful email verification (if not set, shows default success page)
-                  resetPasswordRedirectTo:
-                    type: string
-                    nullable: true
-                    description: URL to redirect users after successful password reset (if not set, shows default success page)
-                  verifyEmailMethod:
-                    type: string
-                    enum: [code, link]
-                  resetPasswordMethod:
-                    type: string
-                    enum: [code, link]
-                  signInRedirectTo:
-                    type: string
-                    nullable: true
-                  createdAt:
-                    type: string
-                    format: date-time
-                  updatedAt:
-                    type: string
-                    format: date-time
-        '400':
-          description: Invalid request
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-
-  /api/auth/users:
-    post:
-      summary: Register new user
-      description: Creates a new user account
-      tags:
-          - Client
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - email
-                - password
-              properties:
-                email:
-                  type: string
-                  format: email
-                  example: user@example.com
-                password:
-                  type: string
-                  description: Password meeting configured requirements (check /api/auth/email/config for current requirements)
-                  example: securepassword123
-                name:
-                  type: string
-                  example: John Doe
-      responses:
-        '200':
-          description: User created successfully
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  user:
-                    $ref: '#/components/schemas/UserResponse'
-                  accessToken:
-                    type: string
-                    nullable: true
-                    description: JWT authentication token (null if email verification required)
-                  requireEmailVerification:
-                    type: boolean
-                    description: Whether email verification is required before login
-                  redirectTo:
-                    type: string
-                    format: uri
-                    description: Optional URL to redirect user after registration (only present if email verification not required)
-        '400':
-          description: Invalid request
-        '409':
-          description: User already exists
-
-    get:
-      summary: List all users (admin only)
-      description: Returns paginated list of users
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      parameters:
-        - name: offset
-          in: query
-          schema:
-            type: string
-            default: '0'
-          description: Number of records to skip
-        - name: limit
-          in: query
-          schema:
-            type: string
-            default: '10'
-          description: Maximum number of records to return
-        - name: search
-          in: query
-          schema:
-            type: string
-          description: Search by email or name
-      responses:
-        '200':
-          description: List of users
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/UserResponse'
-                  pagination:
-                    type: object
-                    properties:
-                      offset:
-                        type: integer
-                      limit:
-                        type: integer
-                      total:
-                        type: integer
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-
-    delete:
-      summary: Delete users (admin only)
-      description: Delete multiple users by their IDs
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                userIds:
-                  type: array
-                  items:
-                    type: string
-              required:
-                - userIds
-      responses:
-        '200':
-          description: Users deleted successfully
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  message:
-                    type: string
-                  deletedCount:
-                    type: integer
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-
-  /api/auth/users/{userId}:
-    get:
-      summary: Get specific user
-      description: Get user details by ID (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      parameters:
-        - name: userId
-          in: path
-          required: true
-          schema:
-            type: string
-            format: uuid
-          description: User ID
-      responses:
-        '200':
-          description: User details
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/UserResponse'
-        '400':
-          description: Invalid user ID format
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-        '404':
-          description: User not found
-
-  /api/auth/sessions:
-    post:
-      summary: User login
-      description: Authenticates user and returns access token
-      tags:
-        - Client
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - email
-                - password
-              properties:
-                email:
-                  type: string
-                  format: email
-                password:
-                  type: string
-      responses:
-        '200':
-          description: Login successful
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  user:
-                    $ref: '#/components/schemas/UserResponse'
-                  accessToken:
-                    type: string
-                  redirectTo:
-                    type: string
-                    format: uri
-                    description: Optional URL to redirect user after login (if configured)
-        '401':
-          description: Invalid credentials
-        '403':
-          description: Email verification required
-
-  /api/auth/sessions/current:
-    get:
-      summary: Get current user
-      description: Returns the currently authenticated user's basic info from JWT token
-      tags:
-        - Client
-      security:
-        - bearerAuth: []
-      responses:
-        '200':
-          description: Current user info
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  user:
-                    type: object
-                    properties:
-                      id:
-                        type: string
-                        format: uuid
-                      email:
-                        type: string
-                        format: email
-                      role:
-                        type: string
-                        enum: [authenticated, project_admin]
-        '401':
-          description: Unauthorized
-
-  /api/auth/admin/sessions:
-    post:
-      summary: Admin login
-      description: Authenticates admin user for dashboard access
-      tags:
-        - Admin
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - email
-                - password
-              properties:
-                email:
-                  type: string
-                  format: email
-                password:
-                  type: string
-      responses:
-        '200':
-          description: Admin login successful
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  user:
-                    $ref: '#/components/schemas/UserResponse'
-                  accessToken:
-                    type: string
-        '401':
-          description: Invalid credentials
-        '403':
-          description: User is not an admin
-
-  /api/auth/admin/sessions/exchange:
-    post:
-      summary: Exchange cloud provider authorization code for admin session
-      description: Verifies an authorization code/JWT from from Insforge Cloud platform and issues an internal admin session token with project_admin role
-      tags:
-        - Admin
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - code
-              properties:
-                code:
-                  type: string
-                  description: Authorization code or JWT from the Insforge
-                  example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-      responses:
-        '200':
-          description: Cloud authorization verified, admin session created
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  user:
-                    $ref: '#/components/schemas/UserResponse'
-                  accessToken:
-                    type: string
-                    description: Internal JWT for admin authentication
-        '400':
-          description: Invalid authorization code or JWT verification failed
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
-  /api/auth/tokens/anon:
-    post:
-      summary: Generate anonymous token
-      description: Generate a non-expiring anonymous JWT token for public API access (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      responses:
-        '200':
-          description: Anonymous token generated successfully
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  accessToken:
-                    type: string
-                    description: Non-expiring anonymous JWT token
-                    example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
-                  message:
-                    type: string
-                    description: Success message
-                    example: "Anonymous token generated successfully (never expires)"
-        '401':
-          description: Unauthorized - requires authentication
-        '403':
-          description: Forbidden - admin access required
-
-  /api/auth/email/send-verification:
-    post:
-      summary: Send email verification (code or link based on config)
-      description: Send email verification using the method configured in auth settings (verifyEmailMethod). When method is 'code', sends a 6-digit numeric code. When method is 'link', sends a magic link. Prevents user enumeration by returning success even if email doesn't exist.
-      tags:
-        - Client
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - email
-              properties:
-                email:
-                  type: string
-                  format: email
-                  example: user@example.com
-      responses:
-        '202':
-          description: Verification email sent (if email exists). Message varies based on configured method.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-                  message:
-                    type: string
-                    example: "If your email is registered, we have sent you a verification code/link. Please check your inbox."
-        '400':
-          description: Invalid request
-
-  /api/auth/email/verify:
-    post:
-      summary: Verify email with code or link
-      description: |
-        Verify email address using the method configured in auth settings (verifyEmailMethod):
-        - Code verification: Provide both `email` and `otp` (6-digit numeric code)
-        - Link verification: Provide only `otp` (64-character hex token from magic link)
-
-        Successfully verified users will receive a session token.
-
-        The email verification link sent to users always points to the backend API endpoint.
-        If `verifyEmailRedirectTo` is configured, the backend will redirect to that URL after successful verification.
-        Otherwise, a default success page is displayed.
-      tags:
-        - Client
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - otp
-              properties:
-                email:
-                  type: string
-                  format: email
-                  description: Required for numeric code verification, omit for magic link verification
-                  example: user@example.com
-                otp:
-                  type: string
-                  description: Either a 6-digit numeric code or a 64-character hex token from magic link
-                  example: "123456"
-      responses:
-        '200':
-          description: Email verified successfully, session created
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  user:
-                    $ref: '#/components/schemas/UserResponse'
-                  accessToken:
-                    type: string
-                    description: JWT authentication token
-                  redirectTo:
-                    type: string
-                    format: uri
-                    description: Optional URL to redirect user after verification (only present if configured)
-        '400':
-          description: Invalid verification code or token
-        '401':
-          description: Verification code/token expired or invalid
-
-  /api/auth/email/send-reset-password:
-    post:
-      summary: Send password reset (code or link based on config)
-      description: Send password reset email using the method configured in auth settings (resetPasswordMethod). When method is 'code', sends a 6-digit numeric code for two-step flow. When method is 'link', sends a magic link. Prevents user enumeration by returning success even if email doesn't exist.
-      tags:
-        - Client
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - email
-              properties:
-                email:
-                  type: string
-                  format: email
-                  example: user@example.com
-      responses:
-        '202':
-          description: Password reset email sent (if email exists). Message varies based on configured method.
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-                  message:
-                    type: string
-                    example: "If your email is registered, we have sent you a password reset code/link. Please check your inbox."
-        '400':
-          description: Invalid request
-
-  /api/auth/email/exchange-reset-password-token:
-    post:
-      summary: Exchange reset password code for reset token
-      description: |
-        Step 1 of two-step password reset flow (only used when resetPasswordMethod is 'code'):
-        1. Verify the 6-digit code sent to user's email
-        2. Return a reset token that can be used to actually reset the password
-
-        This endpoint is not used when resetPasswordMethod is 'link' (magic link flow is direct).
-      tags:
-        - Client
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - email
-                - code
-              properties:
-                email:
-                  type: string
-                  format: email
-                  example: user@example.com
-                code:
-                  type: string
-                  description: 6-digit numeric code from email
-                  example: "123456"
-      responses:
-        '200':
-          description: Code verified successfully, reset token returned
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  token:
-                    type: string
-                    description: Reset token to be used in reset-password endpoint
-                  expiresAt:
-                    type: string
-                    format: date-time
-                    description: Token expiration timestamp
-        '400':
-          description: Invalid request
-        '401':
-          description: Invalid or expired code
-
-  /api/auth/email/reset-password:
-    post:
-      summary: Reset password with token
-      description: |
-        Reset user password with a token. The token can be:
-        - Magic link token (64-character hex token from send-reset-password when method is 'link')
-        - Reset token (from exchange-reset-password-token after code verification when method is 'code')
-
-        Both token types use RESET_PASSWORD purpose and are verified the same way.
-
-        Flow summary:
-        - Code method: send-reset-password → exchange-reset-password-token → reset-password (with resetToken)
-        - Link method: send-reset-password → reset-password (with link token directly)
-      tags:
-        - Client
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - newPassword
-                - otp
-              properties:
-                newPassword:
-                  type: string
-                  description: New password meeting configured requirements
-                  example: newSecurePassword123
-                otp:
-                  type: string
-                  description: Reset token (either from magic link or from exchange-reset-password-token endpoint)
-                  example: "a1b2c3d4..."
-      responses:
-        '200':
-          description: Password reset successfully
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  message:
-                    type: string
-                    example: "Password reset successfully"
-        '400':
-          description: Invalid request or password requirements not met
-        '401':
-          description: Verification code/token expired or invalid
-
-  /api/auth/oauth/configs:
-    get:
-      summary: List all OAuth configurations
-      description: Get all configured OAuth providers (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      responses:
-        '200':
-          description: List of OAuth configurations
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/OAuthConfig'
-                  count:
-                    type: integer
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-
-    post:
-      summary: Create OAuth configuration
-      description: Create a new OAuth provider configuration (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - provider
-              properties:
-                provider:
-                  type: string
-                  enum: [google, github, discord, linkedin, facebook, microsoft]
-                clientId:
-                  type: string
-                clientSecret:
-                  type: string
-                redirectUri:
-                  type: string
-                scopes:
-                  type: array
-                  items:
-                    type: string
-                useSharedKey:
-                  type: boolean
-      responses:
-        '200':
-          description: OAuth configuration created
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OAuthConfig'
-        '400':
-          description: Invalid request
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-
-  /api/auth/oauth/{provider}/config:
-    get:
-      summary: Get OAuth configuration for specific provider
-      description: Get OAuth configuration including client secret (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      parameters:
-        - name: provider
-          in: path
-          required: true
-          schema:
-            type: string
-            enum: [google, github, discord, linkedin, facebook, microsoft]
-      responses:
-        '200':
-          description: OAuth configuration
-          content:
-            application/json:
-              schema:
-                allOf:
-                  - $ref: '#/components/schemas/OAuthConfig'
-                  - type: object
-                    properties:
-                      clientSecret:
-                        type: string
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-        '404':
-          description: Configuration not found
-
-    put:
-      summary: Update OAuth configuration
-      description: Update OAuth provider configuration (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      parameters:
-        - name: provider
-          in: path
-          required: true
-          schema:
-            type: string
-            enum: [google, github, discord, linkedin, facebook, microsoft]
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                clientId:
-                  type: string
-                clientSecret:
-                  type: string
-                redirectUri:
-                  type: string
-                scopes:
-                  type: array
-                  items:
-                    type: string
-                useSharedKey:
-                  type: boolean
-      responses:
-        '200':
-          description: Configuration updated
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OAuthConfig'
-        '400':
-          description: Invalid request
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-        '404':
-          description: Configuration not found
-
-    delete:
-      summary: Delete OAuth configuration
-      description: Delete OAuth provider configuration (admin only)
-      tags:
-        - Admin
-      security:
-        - bearerAuth: []
-      parameters:
-        - name: provider
-          in: path
-          required: true
-          schema:
-            type: string
-            enum: [google, github, discord, linkedin, facebook, microsoft]
-      responses:
-        '200':
-          description: Configuration deleted
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-                  message:
-                    type: string
-        '401':
-          description: Unauthorized
-        '403':
-          description: Forbidden - Admin only
-        '404':
-          description: Configuration not found
-
-  /api/auth/oauth/{provider}:
-    get:
-      summary: Initiate OAuth flow
-      description: Generate OAuth authorization URL for any supported provider
-      tags:
-        - Client
-      parameters:
-        - name: provider
-          in: path
-          required: true
-          schema:
-            type: string
-            enum: [google, github, discord, linkedin, facebook, microsoft]
-        - name: redirect_uri
-          in: query
-          required: true
-          schema:
-            type: string
-            format: uri
-          description: URL to redirect after authentication
-      responses:
-        '200':
-          description: OAuth authorization URL
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  authUrl:
-                    type: string
-                    format: uri
-        '400':
-          description: Invalid request or provider not supported
-        '500':
-          description: OAuth not configured
-
-  /api/auth/oauth/shared/callback/{state}:
-    get:
-      summary: Shared OAuth callback handler
-      description: Handles OAuth callbacks from InsForge Cloud shared OAuth
-      tags:
-        - Client
-      parameters:
-        - name: state
-          in: path
-          required: true
-          schema:
-            type: string
-          description: JWT state parameter
-        - name: success
-          in: query
-          schema:
-            type: string
-          description: Success flag
-        - name: error
-          in: query
-          schema:
-            type: string
-          description: Error message
-        - name: payload
-          in: query
-          schema:
-            type: string
-          description: Base64 encoded user payload
-      responses:
-        '302':
-          description: Redirect to application with access token or error
-          headers:
-            Location:
-              schema:
-                type: string
-                format: uri
-
-  /api/auth/oauth/{provider}/callback:
-    get:
-      summary: Provider-specific OAuth callback
-      description: OAuth callback endpoint for provider-specific flows
-      tags:
-        - Client
-      parameters:
-        - name: provider
-          in: path
-          required: true
-          schema:
-            type: string
-            enum: [google, github, discord, linkedin, facebook, microsoft]
-        - name: code
-          in: query
-          schema:
-            type: string
-          description: Authorization code from OAuth provider
-        - name: state
-          in: query
-          required: true
-          schema:
-            type: string
-          description: JWT state with redirect URI
-        - name: token
-          in: query
-          schema:
-            type: string
-          description: Direct ID token (for some providers)
-      responses:
-        '302':
-          description: Redirect to application with access token
-          headers:
-            Location:
-              schema:
-                type: string
-                format: uri
-                description: Redirect URL with access_token, user_id, email, and name query params
-
-components:
-  securitySchemes:
-    bearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-    apiKey:
-      type: apiKey
-      in: header
-      name: x-api-key
-
-  schemas:
-    UserResponse:
-      type: object
-      properties:
-        id:
-          type: string
-          format: uuid
-        email:
-          type: string
-          format: email
-        name:
-          type: string
-        emailVerified:
-          type: boolean
-        identities:
-          type: array
-          items:
-            type: object
-            properties:
-              provider:
-                type: string
-        providerType:
-          type: string
-        createdAt:
-          type: string
-          format: date-time
-        updatedAt:
-          type: string
-          format: date-time
-
-    OAuthConfig:
-      type: object
-      properties:
-        id:
-          type: string
-          format: uuid
-        provider:
-          type: string
-          enum: [google, github, discord, linkedin, facebook, microsoft]
-        clientId:
-          type: string
-          nullable: true
-        redirectUri:
-          type: string
-          nullable: true
-        scopes:
-          type: array
-          items:
-            type: string
-          nullable: true
-        useSharedKey:
-          type: boolean
-        createdAt:
-          type: string
-          format: date-time
-        updatedAt:
-          type: string
-          format: date-time
-
-    AuthRecord:
-      type: object
-      properties:
-        id:
-          type: string
-          format: uuid
-        email:
-          type: string
-          format: email
-        passwordHash:
-          type: string
-          description: SHA256 hash of password
-        createdAt:
-          type: string
-          format: date-time
-        updatedAt:
-          type: string
-          format: date-time
-
-    ProfileRecord:
-      type: object
-      properties:
-        id:
-          type: string
-          format: uuid
-        authId:
-          type: string
-          format: uuid
-          description: Foreign key to auth table
-        name:
-          type: string
-        avatar_url:
-          type: string
-          nullable: true
-        bio:
-          type: string
-          nullable: true
-        metadata:
-          type: object
-          description: JSONB field for flexible data
-        createdAt:
-          type: string
-          format: date-time
-        updatedAt:
-          type: string
-          format: date-time
-
-    ErrorResponse:
-      type: object
-      required:
-        - error
-        - message
-        - statusCode
-      properties:
-        error:
-          type: string
-          description: Error code for programmatic handling
-          example: "VALIDATION_ERROR"
-        message:
-          type: string
-          description: Human-readable error message
-          example: "Email is already in use"
-        statusCode:
-          type: integer
-          description: HTTP status code
-          example: 400
-        nextActions:
-          type: string
-          description: Suggested action to resolve the error
-          example: "Please use a different email address"
+openapi: 3.0.3
+info:
+  title: Insforge Authentication API
+  version: 2.0.0
+  description: Authentication endpoints with separated auth and profile tables
+
+paths:
+  /api/auth/public-config:
+    get:
+      summary: Get public authentication configuration
+      description: Get all public authentication configuration including OAuth providers and email auth settings (public endpoint)
+      tags:
+        - Client
+      responses:
+        '200':
+          description: Public authentication configuration
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  oAuthProviders:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        provider:
+                          type: string
+                          enum: [google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft]
+                        useSharedKey:
+                          type: boolean
+                  requireEmailVerification:
+                    type: boolean
+                  passwordMinLength:
+                    type: integer
+                    minimum: 4
+                    maximum: 128
+                  requireNumber:
+                    type: boolean
+                  requireLowercase:
+                    type: boolean
+                  requireUppercase:
+                    type: boolean
+                  requireSpecialChar:
+                    type: boolean
+                  verifyEmailRedirectTo:
+                    type: string
+                    nullable: true
+                    description: URL to redirect users after successful email verification (if not set, shows default success page)
+                  resetPasswordRedirectTo:
+                    type: string
+                    nullable: true
+                    description: URL to redirect users after successful password reset (if not set, shows default success page)
+                  verifyEmailMethod:
+                    type: string
+                    enum: [code, link]
+                    description: Method for email verification (code = 6-digit OTP, link = magic link)
+                  resetPasswordMethod:
+                    type: string
+                    enum: [code, link]
+                    description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
+
+  /api/auth/profiles/current:
+    patch:
+      summary: Update current user's profile
+      description: Update the profile of the currently authenticated user
+      tags:
+        - Client
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - profile
+              properties:
+                profile:
+                  type: object
+                  additionalProperties: true
+                  description: Profile data (name, avatar_url, and any custom fields)
+                  properties:
+                    name:
+                      type: string
+                    avatar_url:
+                      type: string
+                      format: uri
+      responses:
+        '200':
+          description: Profile updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProfileResponse'
+        '400':
+          description: Invalid request
+        '401':
+          description: Unauthorized - authentication required
+
+  /api/auth/profiles/{userId}:
+    get:
+      summary: Get user profile by ID
+      description: Get public profile information for a user by their ID (public endpoint)
+      tags:
+        - Client
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: User ID
+      responses:
+        '200':
+          description: User profile
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProfileResponse'
+        '400':
+          description: Invalid user ID format
+        '404':
+          description: User not found
+
+  /api/auth/config:
+    get:
+      summary: Get authentication configuration
+      description: Get current authentication settings including all configuration options (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Authentication configuration
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                    format: uuid
+                  requireEmailVerification:
+                    type: boolean
+                  passwordMinLength:
+                    type: integer
+                    minimum: 4
+                    maximum: 128
+                  requireNumber:
+                    type: boolean
+                  requireLowercase:
+                    type: boolean
+                  requireUppercase:
+                    type: boolean
+                  requireSpecialChar:
+                    type: boolean
+                  verifyEmailRedirectTo:
+                    type: string
+                    nullable: true
+                    description: URL to redirect users after successful email verification (if not set, shows default success page)
+                  resetPasswordRedirectTo:
+                    type: string
+                    nullable: true
+                    description: URL to redirect users after successful password reset (if not set, shows default success page)
+                  verifyEmailMethod:
+                    type: string
+                    enum: [code, link]
+                    description: Method for email verification (code = 6-digit OTP, link = magic link)
+                  resetPasswordMethod:
+                    type: string
+                    enum: [code, link]
+                    description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
+                  signInRedirectTo:
+                    type: string
+                    nullable: true
+                    description: URL to redirect users after successful sign in
+                  createdAt:
+                    type: string
+                    format: date-time
+                  updatedAt:
+                    type: string
+                    format: date-time
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+
+    put:
+      summary: Update authentication configuration
+      description: Update authentication settings (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                requireEmailVerification:
+                  type: boolean
+                passwordMinLength:
+                  type: integer
+                  minimum: 4
+                  maximum: 128
+                requireNumber:
+                  type: boolean
+                requireLowercase:
+                  type: boolean
+                requireUppercase:
+                  type: boolean
+                requireSpecialChar:
+                  type: boolean
+                verifyEmailRedirectTo:
+                  type: string
+                  nullable: true
+                  description: URL to redirect users after successful email verification (if not set, shows default success page)
+                resetPasswordRedirectTo:
+                  type: string
+                  nullable: true
+                  description: URL to redirect users after successful password reset (if not set, shows default success page)
+                verifyEmailMethod:
+                  type: string
+                  enum: [code, link]
+                  description: Method for email verification (code = 6-digit OTP, link = magic link)
+                resetPasswordMethod:
+                  type: string
+                  enum: [code, link]
+                  description: Method for password reset (code = 6-digit OTP + exchange flow, link = magic link)
+                signInRedirectTo:
+                  type: string
+                  nullable: true
+                  description: URL to redirect users after successful sign in
+      responses:
+        '200':
+          description: Configuration updated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                    format: uuid
+                  requireEmailVerification:
+                    type: boolean
+                  passwordMinLength:
+                    type: integer
+                    minimum: 4
+                    maximum: 128
+                  requireNumber:
+                    type: boolean
+                  requireLowercase:
+                    type: boolean
+                  requireUppercase:
+                    type: boolean
+                  requireSpecialChar:
+                    type: boolean
+                  verifyEmailRedirectTo:
+                    type: string
+                    nullable: true
+                    description: URL to redirect users after successful email verification (if not set, shows default success page)
+                  resetPasswordRedirectTo:
+                    type: string
+                    nullable: true
+                    description: URL to redirect users after successful password reset (if not set, shows default success page)
+                  verifyEmailMethod:
+                    type: string
+                    enum: [code, link]
+                  resetPasswordMethod:
+                    type: string
+                    enum: [code, link]
+                  signInRedirectTo:
+                    type: string
+                    nullable: true
+                  createdAt:
+                    type: string
+                    format: date-time
+                  updatedAt:
+                    type: string
+                    format: date-time
+        '400':
+          description: Invalid request
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+
+  /api/auth/users:
+    post:
+      summary: Register new user
+      description: Creates a new user account
+      tags:
+          - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+                - password
+              properties:
+                email:
+                  type: string
+                  format: email
+                  example: user@example.com
+                password:
+                  type: string
+                  description: Password meeting configured requirements (check /api/auth/email/config for current requirements)
+                  example: securepassword123
+                name:
+                  type: string
+                  example: John Doe
+      responses:
+        '200':
+          description: User created successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    $ref: '#/components/schemas/UserResponse'
+                  accessToken:
+                    type: string
+                    nullable: true
+                    description: JWT authentication token (null if email verification required)
+                  requireEmailVerification:
+                    type: boolean
+                    description: Whether email verification is required before login
+                  redirectTo:
+                    type: string
+                    format: uri
+                    description: Optional URL to redirect user after registration (only present if email verification not required)
+        '400':
+          description: Invalid request
+        '409':
+          description: User already exists
+
+    get:
+      summary: List all users (admin only)
+      description: Returns paginated list of users
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: offset
+          in: query
+          schema:
+            type: string
+            default: '0'
+          description: Number of records to skip
+        - name: limit
+          in: query
+          schema:
+            type: string
+            default: '10'
+          description: Maximum number of records to return
+        - name: search
+          in: query
+          schema:
+            type: string
+          description: Search by email or name
+      responses:
+        '200':
+          description: List of users
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/UserResponse'
+                  pagination:
+                    type: object
+                    properties:
+                      offset:
+                        type: integer
+                      limit:
+                        type: integer
+                      total:
+                        type: integer
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+
+    delete:
+      summary: Delete users (admin only)
+      description: Delete multiple users by their IDs
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                userIds:
+                  type: array
+                  items:
+                    type: string
+              required:
+                - userIds
+      responses:
+        '200':
+          description: Users deleted successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  deletedCount:
+                    type: integer
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+
+  /api/auth/users/{userId}:
+    get:
+      summary: Get specific user
+      description: Get user details by ID (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+          description: User ID
+      responses:
+        '200':
+          description: User details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '400':
+          description: Invalid user ID format
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+        '404':
+          description: User not found
+
+  /api/auth/sessions:
+    post:
+      summary: User login
+      description: Authenticates user and returns access token
+      tags:
+        - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+                - password
+              properties:
+                email:
+                  type: string
+                  format: email
+                password:
+                  type: string
+      responses:
+        '200':
+          description: Login successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    $ref: '#/components/schemas/UserResponse'
+                  accessToken:
+                    type: string
+                  redirectTo:
+                    type: string
+                    format: uri
+                    description: Optional URL to redirect user after login (if configured)
+        '401':
+          description: Invalid credentials
+        '403':
+          description: Email verification required
+
+  /api/auth/sessions/current:
+    get:
+      summary: Get current user
+      description: Returns the currently authenticated user's basic info from JWT token
+      tags:
+        - Client
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Current user info
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    type: object
+                    properties:
+                      id:
+                        type: string
+                        format: uuid
+                      email:
+                        type: string
+                        format: email
+                      role:
+                        type: string
+                        enum: [authenticated, project_admin]
+        '401':
+          description: Unauthorized
+
+  /api/auth/admin/sessions:
+    post:
+      summary: Admin login
+      description: Authenticates admin user for dashboard access
+      tags:
+        - Admin
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+                - password
+              properties:
+                email:
+                  type: string
+                  format: email
+                password:
+                  type: string
+      responses:
+        '200':
+          description: Admin login successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    $ref: '#/components/schemas/UserResponse'
+                  accessToken:
+                    type: string
+        '401':
+          description: Invalid credentials
+        '403':
+          description: User is not an admin
+
+  /api/auth/admin/sessions/exchange:
+    post:
+      summary: Exchange cloud provider authorization code for admin session
+      description: Verifies an authorization code/JWT from from Insforge Cloud platform and issues an internal admin session token with project_admin role
+      tags:
+        - Admin
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - code
+              properties:
+                code:
+                  type: string
+                  description: Authorization code or JWT from the Insforge
+                  example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+      responses:
+        '200':
+          description: Cloud authorization verified, admin session created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    $ref: '#/components/schemas/UserResponse'
+                  accessToken:
+                    type: string
+                    description: Internal JWT for admin authentication
+        '400':
+          description: Invalid authorization code or JWT verification failed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/auth/tokens/anon:
+    post:
+      summary: Generate anonymous token
+      description: Generate a non-expiring anonymous JWT token for public API access (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: Anonymous token generated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  accessToken:
+                    type: string
+                    description: Non-expiring anonymous JWT token
+                    example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+                  message:
+                    type: string
+                    description: Success message
+                    example: "Anonymous token generated successfully (never expires)"
+        '401':
+          description: Unauthorized - requires authentication
+        '403':
+          description: Forbidden - admin access required
+
+  /api/auth/email/send-verification:
+    post:
+      summary: Send email verification (code or link based on config)
+      description: Send email verification using the method configured in auth settings (verifyEmailMethod). When method is 'code', sends a 6-digit numeric code. When method is 'link', sends a magic link. Prevents user enumeration by returning success even if email doesn't exist.
+      tags:
+        - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+              properties:
+                email:
+                  type: string
+                  format: email
+                  example: user@example.com
+      responses:
+        '202':
+          description: Verification email sent (if email exists). Message varies based on configured method.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+                    example: "If your email is registered, we have sent you a verification code/link. Please check your inbox."
+        '400':
+          description: Invalid request
+
+  /api/auth/email/verify:
+    post:
+      summary: Verify email with code or link
+      description: |
+        Verify email address using the method configured in auth settings (verifyEmailMethod):
+        - Code verification: Provide both `email` and `otp` (6-digit numeric code)
+        - Link verification: Provide only `otp` (64-character hex token from magic link)
+
+        Successfully verified users will receive a session token.
+
+        The email verification link sent to users always points to the backend API endpoint.
+        If `verifyEmailRedirectTo` is configured, the backend will redirect to that URL after successful verification.
+        Otherwise, a default success page is displayed.
+      tags:
+        - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - otp
+              properties:
+                email:
+                  type: string
+                  format: email
+                  description: Required for numeric code verification, omit for magic link verification
+                  example: user@example.com
+                otp:
+                  type: string
+                  description: Either a 6-digit numeric code or a 64-character hex token from magic link
+                  example: "123456"
+      responses:
+        '200':
+          description: Email verified successfully, session created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  user:
+                    $ref: '#/components/schemas/UserResponse'
+                  accessToken:
+                    type: string
+                    description: JWT authentication token
+                  redirectTo:
+                    type: string
+                    format: uri
+                    description: Optional URL to redirect user after verification (only present if configured)
+        '400':
+          description: Invalid verification code or token
+        '401':
+          description: Verification code/token expired or invalid
+
+  /api/auth/email/send-reset-password:
+    post:
+      summary: Send password reset (code or link based on config)
+      description: Send password reset email using the method configured in auth settings (resetPasswordMethod). When method is 'code', sends a 6-digit numeric code for two-step flow. When method is 'link', sends a magic link. Prevents user enumeration by returning success even if email doesn't exist.
+      tags:
+        - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+              properties:
+                email:
+                  type: string
+                  format: email
+                  example: user@example.com
+      responses:
+        '202':
+          description: Password reset email sent (if email exists). Message varies based on configured method.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+                    example: "If your email is registered, we have sent you a password reset code/link. Please check your inbox."
+        '400':
+          description: Invalid request
+
+  /api/auth/email/exchange-reset-password-token:
+    post:
+      summary: Exchange reset password code for reset token
+      description: |
+        Step 1 of two-step password reset flow (only used when resetPasswordMethod is 'code'):
+        1. Verify the 6-digit code sent to user's email
+        2. Return a reset token that can be used to actually reset the password
+
+        This endpoint is not used when resetPasswordMethod is 'link' (magic link flow is direct).
+      tags:
+        - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - email
+                - code
+              properties:
+                email:
+                  type: string
+                  format: email
+                  example: user@example.com
+                code:
+                  type: string
+                  description: 6-digit numeric code from email
+                  example: "123456"
+      responses:
+        '200':
+          description: Code verified successfully, reset token returned
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token:
+                    type: string
+                    description: Reset token to be used in reset-password endpoint
+                  expiresAt:
+                    type: string
+                    format: date-time
+                    description: Token expiration timestamp
+        '400':
+          description: Invalid request
+        '401':
+          description: Invalid or expired code
+
+  /api/auth/email/reset-password:
+    post:
+      summary: Reset password with token
+      description: |
+        Reset user password with a token. The token can be:
+        - Magic link token (64-character hex token from send-reset-password when method is 'link')
+        - Reset token (from exchange-reset-password-token after code verification when method is 'code')
+
+        Both token types use RESET_PASSWORD purpose and are verified the same way.
+
+        Flow summary:
+        - Code method: send-reset-password → exchange-reset-password-token → reset-password (with resetToken)
+        - Link method: send-reset-password → reset-password (with link token directly)
+      tags:
+        - Client
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - newPassword
+                - otp
+              properties:
+                newPassword:
+                  type: string
+                  description: New password meeting configured requirements
+                  example: newSecurePassword123
+                otp:
+                  type: string
+                  description: Reset token (either from magic link or from exchange-reset-password-token endpoint)
+                  example: "a1b2c3d4..."
+      responses:
+        '200':
+          description: Password reset successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: "Password reset successfully"
+        '400':
+          description: Invalid request or password requirements not met
+        '401':
+          description: Verification code/token expired or invalid
+
+  /api/auth/oauth/configs:
+    get:
+      summary: List all OAuth configurations
+      description: Get all configured OAuth providers (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      responses:
+        '200':
+          description: List of OAuth configurations
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/OAuthConfig'
+                  count:
+                    type: integer
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+
+    post:
+      summary: Create OAuth configuration
+      description: Create a new OAuth provider configuration (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - provider
+              properties:
+                provider:
+                  type: string
+                  enum: [google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft]
+                clientId:
+                  type: string
+                clientSecret:
+                  type: string
+                redirectUri:
+                  type: string
+                scopes:
+                  type: array
+                  items:
+                    type: string
+                useSharedKey:
+                  type: boolean
+      responses:
+        '200':
+          description: OAuth configuration created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthConfig'
+        '400':
+          description: Invalid request
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+
+  /api/auth/oauth/{provider}/config:
+    get:
+      summary: Get OAuth configuration for specific provider
+      description: Get OAuth configuration including client secret (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft]
+      responses:
+        '200':
+          description: OAuth configuration
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '#/components/schemas/OAuthConfig'
+                  - type: object
+                    properties:
+                      clientSecret:
+                        type: string
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+        '404':
+          description: Configuration not found
+
+    put:
+      summary: Update OAuth configuration
+      description: Update OAuth provider configuration (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                clientId:
+                  type: string
+                clientSecret:
+                  type: string
+                redirectUri:
+                  type: string
+                scopes:
+                  type: array
+                  items:
+                    type: string
+                useSharedKey:
+                  type: boolean
+      responses:
+        '200':
+          description: Configuration updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthConfig'
+        '400':
+          description: Invalid request
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+        '404':
+          description: Configuration not found
+
+    delete:
+      summary: Delete OAuth configuration
+      description: Delete OAuth provider configuration (admin only)
+      tags:
+        - Admin
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft]
+      responses:
+        '200':
+          description: Configuration deleted
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+        '401':
+          description: Unauthorized
+        '403':
+          description: Forbidden - Admin only
+        '404':
+          description: Configuration not found
+
+  /api/auth/oauth/{provider}:
+    get:
+      summary: Initiate OAuth flow
+      description: Generate OAuth authorization URL for any supported provider
+      tags:
+        - Client
+      parameters:
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft]
+        - name: redirect_uri
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uri
+          description: URL to redirect after authentication
+      responses:
+        '200':
+          description: OAuth authorization URL
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  authUrl:
+                    type: string
+                    format: uri
+        '400':
+          description: Invalid request or provider not supported
+        '500':
+          description: OAuth not configured
+
+  /api/auth/oauth/shared/callback/{state}:
+    get:
+      summary: Shared OAuth callback handler
+      description: Handles OAuth callbacks from InsForge Cloud shared OAuth
+      tags:
+        - Client
+      parameters:
+        - name: state
+          in: path
+          required: true
+          schema:
+            type: string
+          description: JWT state parameter
+        - name: success
+          in: query
+          schema:
+            type: string
+          description: Success flag
+        - name: error
+          in: query
+          schema:
+            type: string
+          description: Error message
+        - name: payload
+          in: query
+          schema:
+            type: string
+          description: Base64 encoded user payload
+      responses:
+        '302':
+          description: Redirect to application with access token or error
+          headers:
+            Location:
+              schema:
+                type: string
+                format: uri
+
+  /api/auth/oauth/{provider}/callback:
+    get:
+      summary: Provider-specific OAuth callback
+      description: OAuth callback endpoint for provider-specific flows
+      tags:
+        - Client
+      parameters:
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft]
+        - name: code
+          in: query
+          schema:
+            type: string
+          description: Authorization code from OAuth provider
+        - name: state
+          in: query
+          required: true
+          schema:
+            type: string
+          description: JWT state with redirect URI
+        - name: token
+          in: query
+          schema:
+            type: string
+          description: Direct ID token (for some providers)
+      responses:
+        '302':
+          description: Redirect to application with access token
+          headers:
+            Location:
+              schema:
+                type: string
+                format: uri
+                description: Redirect URL with access_token, user_id, email, and name query params
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+    apiKey:
+      type: apiKey
+      in: header
+      name: x-api-key
+
+  schemas:
+    UserResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        metadata:
+          type: object
+          additionalProperties: true
+        emailVerified:
+          type: boolean
+        providers:
+          type: array
+          items:
+            type: string
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    ProfileResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: User ID
+        profile:
+          type: object
+          nullable: true
+          additionalProperties: true
+          description: User profile data (can contain custom fields)
+          properties:
+            name:
+              type: string
+            avatar_url:
+              type: string
+              format: uri
+
+    OAuthConfig:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        provider:
+          type: string
+          enum: [google, github, discord, linkedin, facebook, instagram, tiktok, apple, x, spotify, microsoft]
+        clientId:
+          type: string
+          nullable: true
+        redirectUri:
+          type: string
+          nullable: true
+        scopes:
+          type: array
+          items:
+            type: string
+          nullable: true
+        useSharedKey:
+          type: boolean
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    AuthRecord:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        passwordHash:
+          type: string
+          description: SHA256 hash of password
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    ProfileRecord:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        authId:
+          type: string
+          format: uuid
+          description: Foreign key to auth table
+        name:
+          type: string
+        avatar_url:
+          type: string
+          nullable: true
+        bio:
+          type: string
+          nullable: true
+        metadata:
+          type: object
+          description: JSONB field for flexible data
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    ErrorResponse:
+      type: object
+      required:
+        - error
+        - message
+        - statusCode
+      properties:
+        error:
+          type: string
+          description: Error code for programmatic handling
+          example: "VALIDATION_ERROR"
+        message:
+          type: string
+          description: Human-readable error message
+          example: "Email is already in use"
+        statusCode:
+          type: integer
+          description: HTTP status code
+          example: 400
+        nextActions:
+          type: string
+          description: Suggested action to resolve the error
+          example: "Please use a different email address"