openapi.yaml

openapi: "3.1.0"
info:
  title: Platform API
  description: |
    Production-grade SaaS platform API. Modular monolith with RBAC+PBAC authorization,
    multi-email/phone support, feature flags, and comprehensive audit logging.

    ## Authentication
    Most endpoints require a valid JWT access token in the `Authorization: Bearer <token>` header.

    ## Rate Limiting
    Rate limits are applied per-endpoint. Response headers indicate limit status:
    - `X-RateLimit-Limit` — Maximum requests allowed
    - `X-RateLimit-Remaining` — Requests remaining in window
    - `X-RateLimit-Reset` — Unix timestamp when window resets

    ## Error Format
    All errors follow RFC 7807 Problem Details:
    ```json
    {
      "type": "https://api.platform.dev/errors/validation",
      "title": "Validation Error",
      "status": 422,
      "detail": "Email is required",
      "instance": "/auth/register",
      "errors": [{"field": "email", "message": "required"}]
    }
    ```
  version: "1.0.0"
  contact:
    name: Platform Support
  license:
    name: Proprietary

servers:
  - url: http://localhost:8080
    description: Local development
  - url: https://api.staging.platform.dev
    description: Staging
  - url: https://api.platform.dev
    description: Production

tags:
  - name: Health
    description: Health and readiness checks
  - name: Auth
    description: Authentication, registration, and account management
  - name: Users
    description: User profile and current-user management
  - name: User Emails
    description: Multi-email management per user
  - name: User Phones
    description: Multi-phone management per user
  - name: Workspaces
    description: Workspace CRUD, settings, and audit
  - name: Workspace Members
    description: Workspace membership management
  - name: Invitations
    description: Workspace invitation lifecycle
  - name: Feature Flags
    description: System feature flag administration, resolution, and overrides

paths:
  # ──────────────────────────────────────────────
  # Health
  # ──────────────────────────────────────────────
  /healthz:
    get:
      operationId: healthLiveness
      tags: [Health]
      summary: Liveness probe
      description: Returns 200 if the process is alive. Used by Kubernetes livenessProbe.
      responses:
        "200":
          description: Service is alive
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /readyz:
    get:
      operationId: healthReadiness
      tags: [Health]
      summary: Readiness probe
      description: |
        Returns 200 if the service is ready to accept traffic.
        Checks: PostgreSQL connectivity, Redis connectivity, migrations complete, module init.
        Used by Kubernetes readinessProbe.
      responses:
        "200":
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadyResponse"
        "503":
          description: Service is not ready
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadyResponse"

  # ──────────────────────────────────────────────
  # Auth
  # ──────────────────────────────────────────────
  /auth/register:
    post:
      operationId: authRegister
      tags: [Auth]
      summary: Register a new user
      description: |
        Creates a new user account. Sends email verification to the primary email.
        The user is not activated until email is verified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterRequest"
      responses:
        "201":
          description: User created, verification email sent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/ValidationError"

  /auth/login:
    post:
      operationId: authLogin
      tags: [Auth]
      summary: Log in
      description: |
        Authenticates a user by email+password. Returns access and refresh tokens.
        Respects account lockout after failed attempts. Rate limited to 5/min per IP.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: Login successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "423":
          description: Account locked
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetail"

  /auth/logout:
    post:
      operationId: authLogout
      tags: [Auth]
      summary: Log out
      description: Revokes the current refresh token and invalidates the session.
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Logged out successfully
        "401":
          $ref: "#/components/responses/Unauthorized"

  /auth/logout-all:
    post:
      operationId: authLogoutAll
      tags: [Auth]
      summary: Log out of all sessions
      description: Revokes all refresh tokens for the current user across all devices.
      security:
        - bearerAuth: []
      responses:
        "204":
          description: All sessions revoked
        "401":
          $ref: "#/components/responses/Unauthorized"

  /auth/refresh:
    post:
      operationId: authRefresh
      tags: [Auth]
      summary: Refresh access token
      description: |
        Exchanges a valid refresh token for a new access+refresh token pair.
        The old refresh token is revoked (rotation). Detects reuse and revokes all tokens.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefreshRequest"
      responses:
        "200":
          description: Tokens refreshed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          description: Invalid or reused refresh token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProblemDetail"

  /auth/verify-email:
    post:
      operationId: authVerifyEmail
      tags: [Auth]
      summary: Verify email address
      description: Verifies a specific email address via verification token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailVerifyRequest"
      responses:
        "204":
          description: Email verified
        "400":
          description: Invalid or expired token

  /auth/verify-email/resend:
    post:
      operationId: authResendEmailVerification
      tags: [Auth]
      summary: Resend email verification
      description: Resends the verification email. Rate limited with cooldown.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email_id]
              properties:
                email_id:
                  type: string
                  format: uuid
      responses:
        "204":
          description: Verification email resent
        "400":
          description: Email already verified or cooldown active

  /auth/verify-phone:
    post:
      operationId: authVerifyPhone
      tags: [Auth]
      summary: Verify phone number
      description: Verifies a specific phone number via SMS code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PhoneVerifyRequest"
      responses:
        "204":
          description: Phone verified
        "400":
          description: Invalid or expired code

  /auth/verify-phone/resend:
    post:
      operationId: authResendPhoneVerification
      tags: [Auth]
      summary: Resend phone verification
      description: Resends the SMS verification code. Rate limited with cooldown.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phone_id]
              properties:
                phone_id:
                  type: string
                  format: uuid
      responses:
        "204":
          description: Verification code resent
        "400":
          description: Phone already verified or cooldown active

  /auth/forgot-password:
    post:
      operationId: authForgotPassword
      tags: [Auth]
      summary: Request password reset
      description: |
        Sends a password reset email. Always returns 200 to prevent email enumeration.
        Rate limited to 3/min per email.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: #/components/schemas/ForgotPasswordRequest
      responses:
        "200":
          description: If the email exists, a reset link has been sent

  /auth/reset-password:
    post:
      operationId: authResetPassword
      tags: [Auth]
      summary: Reset password
      description: Resets password using a valid reset token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetPasswordRequest"
      responses:
        "204":
          description: Password reset successful
        "400":
          description: Invalid or expired token

  /auth/mfa/enable:
    post:
      operationId: authMfaEnable
      tags: [Auth]
      summary: Enable MFA
      description: Generates a TOTP secret and returns QR code URL and recovery codes.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: MFA setup initiated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MfaEnableResponse"
        "409":
          description: MFA already enabled

  /auth/mfa/verify:
    post:
      operationId: authMfaVerify
      tags: [Auth]
      summary: Verify MFA setup
      description: Verifies a TOTP code to complete MFA activation.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MfaVerifyRequest"
      responses:
        "204":
          description: MFA enabled
        "401":
          description: Invalid TOTP code

  /auth/mfa/disable:
    post:
      operationId: authMfaDisable
      tags: [Auth]
      summary: Disable MFA
      description: Disables MFA. Requires a valid TOTP code for confirmation.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MfaVerifyRequest"
      responses:
        "204":
          description: MFA disabled
        "401":
          description: Invalid TOTP code

  # ──────────────────────────────────────────────
  # Users (current user)
  # ──────────────────────────────────────────────
  /users/me:
    get:
      operationId: getMe
      tags: [Users]
      summary: Get current user profile
      description: Returns the authenticated user's profile including emails, phones, and roles.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Current user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurrentUserResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

    put:
      operationId: updateMe
      tags: [Users]
      summary: Update current user profile
      description: Updates the current user's display name and metadata.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/ValidationError"

    delete:
      operationId: deleteMe
      tags: [Users]
      summary: Delete current user
      description: Permanently deletes the current user account and all associated data.
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Account deleted
        "401":
          $ref: "#/components/responses/Unauthorized"

  /users/me/avatar:
    put:
      operationId: updateMeAvatar
      tags: [Users]
      summary: Update avatar
      description: Uploads a new avatar image for the current user.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [avatar]
              properties:
                avatar:
                  type: string
                  format: binary
                  description: Avatar image (JPEG, PNG, max 5MB)
      responses:
        "200":
          description: Avatar updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  avatar_url:
                    type: string
                    format: uri
        "401":
          $ref: "#/components/responses/Unauthorized"
        "413":
          description: File too large

  /users/me/password:
    put:
      operationId: updateMePassword
      tags: [Users]
      summary: Change password
      description: Changes the current user's password. Requires current password.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChangePasswordRequest"
      responses:
        "204":
          description: Password changed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/ValidationError"

  /users/me/preferences:
    put:
      operationId: updateMePreferences
      tags: [Users]
      summary: Update preferences
      description: Updates the current user's preference settings.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSettingsRequest"
      responses:
        "200":
          description: Preferences updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Setting"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /users/me/workspaces:
    get:
      operationId: getMyWorkspaces
      tags: [Users]
      summary: List my workspaces
      description: Returns all workspaces the current user is a member of.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of workspaces
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ──────────────────────────────────────────────
  # User Emails
  # ──────────────────────────────────────────────
  /users/me/emails:
    get:
      operationId: listMyEmails
      tags: [User Emails]
      summary: List my emails
      description: Returns all email addresses for the current user.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of emails
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/UserEmail"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: addMyEmail
      tags: [User Emails]
      summary: Add email address
      description: |
        Adds a new email address. Sends verification email.
        Maximum 5 emails per user.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddEmailRequest"
      responses:
        "201":
          description: Email added, verification sent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserEmail"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/ValidationError"

  /users/me/emails/{email_id}:
    delete:
      operationId: removeMyEmail
      tags: [User Emails]
      summary: Remove email address
      description: |
        Removes an email address. Cannot remove the primary email.
        Cannot remove the last verified email.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/EmailId"
      responses:
        "204":
          description: Email removed
        "400":
          description: Cannot remove primary or last verified email
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /users/me/emails/{email_id}/set-primary:
    post:
      operationId: setMyPrimaryEmail
      tags: [User Emails]
      summary: Set primary email
      description: Sets an email as the primary contact email.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/EmailId"
      responses:
        "204":
          description: Primary email updated
        "400":
          description: Email not verified
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /users/me/emails/{email_id}/verify:
    post:
      operationId: verifyMyEmail
      tags: [User Emails]
      summary: Verify email
      description: Verifies a specific email via token (for logged-in users).
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/EmailId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [token]
              properties:
                token:
                  type: string
                  format: uuid
      responses:
        "204":
          description: Email verified
        "400":
          description: Invalid or expired token

  /users/me/emails/{email_id}/verify/resend:
    post:
      operationId: resendMyEmailVerification
      tags: [User Emails]
      summary: Resend email verification
      description: Resends the verification email. Rate limited with cooldown.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/EmailId"
      responses:
        "204":
          description: Verification email resent
        "400":
          description: Email already verified or cooldown active

  # ──────────────────────────────────────────────
  # User Phones
  # ──────────────────────────────────────────────
  /users/me/phones:
    get:
      operationId: listMyPhones
      tags: [User Phones]
      summary: List my phones
      description: Returns all phone numbers for the current user.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of phones
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/UserPhone"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: addMyPhone
      tags: [User Phones]
      summary: Add phone number
      description: |
        Adds a new phone number. Sends SMS verification code.
        Maximum 3 phones per user.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddPhoneRequest"
      responses:
        "201":
          description: Phone added, verification code sent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserPhone"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/ValidationError"

  /users/me/phones/{phone_id}:
    delete:
      operationId: removeMyPhone
      tags: [User Phones]
      summary: Remove phone number
      description: Removes a phone number. Cannot remove primary or last verified phone.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PhoneId"
      responses:
        "204":
          description: Phone removed
        "400":
          description: Cannot remove primary or last verified phone
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /users/me/phones/{phone_id}/set-primary:
    post:
      operationId: setMyPrimaryPhone
      tags: [User Phones]
      summary: Set primary phone
      description: Sets a phone as the primary contact number.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PhoneId"
      responses:
        "204":
          description: Primary phone updated
        "400":
          description: Phone not verified
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /users/me/phones/{phone_id}/verify:
    post:
      operationId: verifyMyPhone
      tags: [User Phones]
      summary: Verify phone
      description: Verifies a specific phone via SMS code (for logged-in users).
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PhoneId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code:
                  type: string
                  minLength: 6
                  maxLength: 6
      responses:
        "204":
          description: Phone verified
        "400":
          description: Invalid or expired code

  /users/me/phones/{phone_id}/verify/resend:
    post:
      operationId: resendMyPhoneVerification
      tags: [User Phones]
      summary: Resend phone verification
      description: Resends the SMS verification code. Rate limited with cooldown.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PhoneId"
      responses:
        "204":
          description: Verification code resent
        "400":
          description: Phone already verified or cooldown active

  # ──────────────────────────────────────────────
  # Feature Flags (admin + resolution)
  # ──────────────────────────────────────────────
  /feature-flags:
    get:
      operationId: listFeatureFlags
      tags: [Feature Flags]
      summary: List all feature flags
      description: Returns all system feature flags with their defaults. Requires platform_admin.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of feature flags
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/FeatureFlag"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

    post:
      operationId: createFeatureFlag
      tags: [Feature Flags]
      summary: Create feature flag
      description: Creates a new system feature flag. Requires platform_admin.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateFeatureFlagRequest"
      responses:
        "201":
          description: Flag created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureFlag"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/ValidationError"

  /feature-flags/{flag_id}:
    get:
      operationId: getFeatureFlag
      tags: [Feature Flags]
      summary: Get feature flag details
      description: Returns a feature flag with all overrides. Requires platform_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/FlagId"
      responses:
        "200":
          description: Feature flag details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureFlag"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      operationId: updateFeatureFlag
      tags: [Feature Flags]
      summary: Update feature flag
      description: Updates a system feature flag's default value. Requires platform_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/FlagId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateFeatureFlagRequest"
      responses:
        "200":
          description: Flag updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureFlag"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"

    delete:
      operationId: deleteFeatureFlag
      tags: [Feature Flags]
      summary: Delete feature flag
      description: Deletes a system feature flag and all overrides. Requires platform_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/FlagId"
      responses:
        "204":
          description: Flag deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /feature-flags/{flag_id}/toggle:
    post:
      operationId: toggleFeatureFlag
      tags: [Feature Flags]
      summary: Toggle feature flag
      description: Toggles a boolean feature flag on/off. Requires platform_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/FlagId"
      responses:
        "200":
          description: Flag toggled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureFlag"
        "400":
          description: Flag is not boolean type
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /feature-flags/resolve:
    get:
      operationId: resolveFeatureFlags
      tags: [Feature Flags]
      summary: Resolve feature flags
      description: |
        Returns all feature flags resolved for the current user and workspace.
        Resolution order: user override → workspace override → system default.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Resolved flags
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ResolvedFeatureFlag"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /feature-flags/resolve-batch:
    post:
      operationId: resolveFeatureFlagsBatch
      tags: [Feature Flags]
      summary: Resolve multiple feature flags
      description: |
        Resolves a specific set of feature flags by keys. Useful for checking
        multiple flags in a single request. Rate limited to 10/min.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [keys]
              properties:
                keys:
                  type: array
                  items:
                    type: string
                  description: List of flag keys to resolve
      responses:
        "200":
          description: Resolved flags
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ResolvedFeatureFlag"
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ──────────────────────────────────────────────
  # Workspace Feature Flag Overrides
  # ──────────────────────────────────────────────
  /workspaces/{workspace_id}/feature-flags:
    get:
      operationId: listWorkspaceFeatureFlagOverrides
      tags: [Feature Flags]
      summary: List workspace flag overrides
      description: Returns all feature flag overrides for a workspace.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: Workspace flag overrides
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/FeatureFlagOverride"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /workspaces/{workspace_id}/feature-flags/{flag_id}:
    put:
      operationId: setWorkspaceFeatureFlagOverride
      tags: [Feature Flags]
      summary: Set workspace flag override
      description: |
        Sets a feature flag override for a workspace. Requires workspace_admin.
        Value must match the flag's value_type (boolean or string).
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/FlagId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetFeatureFlagOverrideRequest"
      responses:
        "200":
          description: Override set
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureFlagOverride"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"

    delete:
      operationId: deleteWorkspaceFeatureFlagOverride
      tags: [Feature Flags]
      summary: Delete workspace flag override
      description: Removes a workspace override. The system default will take effect.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/FlagId"
      responses:
        "204":
          description: Override deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  # ──────────────────────────────────────────────
  # User-level Feature Flag Overrides
  # ──────────────────────────────────────────────
  /workspaces/{workspace_id}/members/{member_id}/feature-flags:
    get:
      operationId: listUserFeatureFlagOverrides
      tags: [Feature Flags]
      summary: List user flag overrides
      description: Returns all feature flag overrides for a specific user in a workspace.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/MemberId"
      responses:
        "200":
          description: User flag overrides
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/FeatureFlagOverride"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /workspaces/{workspace_id}/members/{member_id}/feature-flags/{flag_id}:
    put:
      operationId: setUserFeatureFlagOverride
      tags: [Feature Flags]
      summary: Set user flag override
      description: |
        Sets a feature flag override for a specific user in a workspace.
        Requires workspace_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/MemberId"
        - $ref: "#/components/parameters/FlagId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetFeatureFlagOverrideRequest"
      responses:
        "200":
          description: Override set
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeatureFlagOverride"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

    delete:
      operationId: deleteUserFeatureFlagOverride
      tags: [Feature Flags]
      summary: Delete user flag override
      description: Removes a user-level override. The workspace or system default will take effect.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/MemberId"
        - $ref: "#/components/parameters/FlagId"
      responses:
        "204":
          description: Override deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  # ──────────────────────────────────────────────
  # Workspaces
  # ──────────────────────────────────────────────
  /workspaces:
    get:
      operationId: listWorkspaces
      tags: [Workspaces]
      summary: List workspaces
      description: Returns all workspaces the current user is a member of.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: List of workspaces
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"

    post:
      operationId: createWorkspace
      tags: [Workspaces]
      summary: Create workspace
      description: Creates a new workspace. The creator becomes workspace_admin.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceRequest"
      responses:
        "201":
          description: Workspace created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "422":
          $ref: "#/components/responses/ValidationError"

  /workspaces/{workspace_id}:
    get:
      operationId: getWorkspace
      tags: [Workspaces]
      summary: Get workspace
      description: Returns workspace details. Requires workspace membership.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: Workspace details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      operationId: updateWorkspace
      tags: [Workspaces]
      summary: Update workspace
      description: Updates workspace name, slug, or settings. Requires workspace_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkspaceRequest"
      responses:
        "200":
          description: Workspace updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"

    delete:
      operationId: deleteWorkspace
      tags: [Workspaces]
      summary: Delete workspace
      description: Permanently deletes a workspace and all its data. Requires workspace_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "204":
          description: Workspace deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  # ──────────────────────────────────────────────
  # Workspace Members
  # ──────────────────────────────────────────────
  /workspaces/{workspace_id}/members:
    get:
      operationId: listMembers
      tags: [Workspace Members]
      summary: List members
      description: Returns all members of a workspace with their roles.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: List of members
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/WorkspaceMember"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /workspaces/{workspace_id}/members/{member_id}/role:
    put:
      operationId: updateMemberRole
      tags: [Workspace Members]
      summary: Update member role
      description: Updates a member's role. Checks SSD/DSD constraints. Requires workspace_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/MemberId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateMemberRoleRequest"
      responses:
        "200":
          description: Role updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceMember"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: Violates SSD/DSD constraint

  /workspaces/{workspace_id}/members/{member_id}:
    delete:
      operationId: removeMember
      tags: [Workspace Members]
      summary: Remove member
      description: Removes a member from the workspace. Requires workspace_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/MemberId"
      responses:
        "204":
          description: Member removed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  # ──────────────────────────────────────────────
  # Invitations
  # ──────────────────────────────────────────────
  /workspaces/{workspace_id}/invitations:
    get:
      operationId: listInvitations
      tags: [Invitations]
      summary: List pending invitations
      description: Returns all pending invitations for the workspace.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: List of invitations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Invitation"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

    post:
      operationId: createInvitation
      tags: [Invitations]
      summary: Create invitation
      description: |
        Sends an invitation email to a user. If the user doesn't exist, they can register
        and join automatically. Expires in 7 days. Requires workspace_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateInvitationRequest"
      responses:
        "201":
          description: Invitation created and email sent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invitation"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"

  /invitations/{token}/accept:
    post:
      operationId: acceptInvitation
      tags: [Invitations]
      summary: Accept invitation
      description: |
        Accepts a workspace invitation via token. If the user is not registered,
        they must register first. The token is single-use and expires in 7 days.
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "201":
          description: Joined workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceMember"
        "400":
          description: Invalid or expired token
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ──────────────────────────────────────────────
  # Workspace Settings
  # ──────────────────────────────────────────────
  /workspaces/{workspace_id}/settings:
    get:
      operationId: getWorkspaceSettings
      tags: [Workspaces]
      summary: Get workspace settings
      description: Returns all workspace settings as key-value pairs.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      responses:
        "200":
          description: Workspace settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Setting"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

    put:
      operationId: updateWorkspaceSettings
      tags: [Workspaces]
      summary: Update workspace settings
      description: |
        Bulk-updates workspace settings. Accepts an array of key-value pairs.
        Requires workspace_admin.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSettingsRequest"
      responses:
        "200":
          description: Settings updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Setting"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"

  # ──────────────────────────────────────────────
  # Audit Logs
  # ──────────────────────────────────────────────
  /workspaces/{workspace_id}/audit:
    get:
      operationId: listAuditLogs
      tags: [Workspaces]
      summary: List audit logs
      description: |
        Returns audit log entries for a workspace. Requires workspace_admin or platform_admin.
        Supports filtering by actor, action, resource type, and date range.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - name: actor_id
          in: query
          schema:
            type: string
            format: uuid
        - name: action
          in: query
          schema:
            type: string
            enum: [create, update, delete, login, logout, invite, accept_invitation]
        - name: resource_type
          in: query
          schema:
            type: string
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/PerPageParam"
      responses:
        "200":
          description: Audit log entries
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedAuditLogs"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

components:
  # ──────────────────────────────────────────────
  # Security
  # ──────────────────────────────────────────────
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token from /auth/login or /auth/refresh

  # ──────────────────────────────────────────────
  # Parameters
  # ──────────────────────────────────────────────
  parameters:
    EmailId:
      name: email_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    PhoneId:
      name: phone_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    WorkspaceId:
      name: workspace_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    MemberId:
      name: member_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    FlagId:
      name: flag_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    PerPageParam:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

  # ──────────────────────────────────────────────
  # Reusable Responses
  # ──────────────────────────────────────────────
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemDetail"
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemDetail"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemDetail"
    Conflict:
      description: Resource already exists
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemDetail"
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProblemDetail"

  # ──────────────────────────────────────────────
  # Schemas
  # ──────────────────────────────────────────────
  schemas:
    # ── Health ──
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: ok

    ReadyResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        checks:
          type: object
          properties:
            database:
              type: string
              example: ok
            redis:
              type: string
              example: ok
            migrations:
              type: string
              example: ok
            module_init:
              type: string
              example: ok

    # ── Error ──
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          format: uri
          example: https://api.platform.dev/errors/validation
        title:
          type: string
          example: Validation Error
        status:
          type: integer
          example: 422
        detail:
          type: string
          example: Email is required
        instance:
          type: string
          example: /auth/register
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string

    # ── Auth ──
    RegisterRequest:
      type: object
      required: [email, password, display_name]
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        password:
          type: string
          format: password
          minLength: 8
          example: SecureP@ss123
        display_name:
          type: string
          minLength: 2
          maxLength: 100
          example: John Doe

    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password

    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Access token TTL in seconds
          example: 900

    RefreshRequest:
      type: object
      required: [refresh_token]
      properties:
        refresh_token:
          type: string

    ChangePasswordRequest:
      type: object
      required: [current_password, new_password]
      properties:
        current_password:
          type: string
          format: password
        new_password:
          type: string
          format: password
          minLength: 8

    MfaEnableResponse:
      type: object
      properties:
        secret:
          type: string
          description: TOTP secret (for QR code generation)
        qr_url:
          type: string
          format: uri
          description: otpauth:// URL for QR code
        recovery_codes:
          type: array
          items:
            type: string
          description: One-time recovery codes

    MfaVerifyRequest:
      type: object
      required: [code]
      properties:
        code:
          type: string
          minLength: 6
          maxLength: 6
          description: 6-digit TOTP code

    ForgotPasswordRequest:
      type: object
      required: [email]
      properties:
        email:
          type: string
          format: email

    ResetPasswordRequest:
      type: object
      required: [token, new_password]
      properties:
        token:
          type: string
          format: uuid
        new_password:
          type: string
          format: password
          minLength: 8

    EmailVerifyRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string
          format: uuid
          description: Email verification token

    PhoneVerifyRequest:
      type: object
      required: [phone_id, code]
      properties:
        phone_id:
          type: string
          format: uuid
        code:
          type: string
          minLength: 6
          maxLength: 6

    # ── User ──
    UserResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type: string
        avatar_url:
          type: string
          format: uri
        is_active:
          type: boolean
        mfa_enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CurrentUserResponse:
      allOf:
        - $ref: "#/components/schemas/UserResponse"
        - type: object
          properties:
            emails:
              type: array
              items:
                $ref: "#/components/schemas/UserEmail"
            phones:
              type: array
              items:
                $ref: "#/components/schemas/UserPhone"
            roles:
              type: array
              items:
                type: string
              example: ["workspace_admin"]

    UpdateUserRequest:
      type: object
      properties:
        display_name:
          type: string
          minLength: 2
          maxLength: 100
        avatar_url:
          type: string
          format: uri

    # ── User Email ──
    UserEmail:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        is_primary:
          type: boolean
        is_verified:
          type: boolean
        created_at:
          type: string
          format: date-time

    AddEmailRequest:
      type: object
      required: [email]
      properties:
        email:
          type: string
          format: email

    # ── User Phone ──
    UserPhone:
      type: object
      properties:
        id:
          type: string
          format: uuid
        phone_number:
          type: string
          example: "+1234567890"
        country_code:
          type: string
          example: "+1"
        is_primary:
          type: boolean
        is_verified:
          type: boolean
        created_at:
          type: string
          format: date-time

    AddPhoneRequest:
      type: object
      required: [phone_number, country_code]
      properties:
        phone_number:
          type: string
          example: "1234567890"
        country_code:
          type: string
          example: "+1"

    # ── Workspace ──
    Workspace:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Acme Corp
        slug:
          type: string
          example: acme-corp
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateWorkspaceRequest:
      type: object
      required: [name, slug]
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
          example: Acme Corp
        slug:
          type: string
          pattern: "^[a-z0-9-]+$"
          minLength: 3
          maxLength: 50
          example: acme-corp

    UpdateWorkspaceRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 100
        slug:
          type: string
          pattern: "^[a-z0-9-]+$"
          minLength: 3
          maxLength: 50

    # ── Workspace Members ──
    WorkspaceMember:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        display_name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [workspace_admin, editor, member, viewer]
        joined_at:
          type: string
          format: date-time

    UpdateMemberRoleRequest:
      type: object
      required: [role]
      properties:
        role:
          type: string
          enum: [workspace_admin, editor, member, viewer]

    # ── Invitations ──
    Invitation:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        role:
          type: string
          enum: [workspace_admin, editor, member, viewer]
        status:
          type: string
          enum: [pending, accepted, expired, revoked]
        invited_by:
          type: string
          format: uuid
        token:
          type: string
          format: uuid
          description: Invitation token (included on creation)
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time

    CreateInvitationRequest:
      type: object
      required: [email, role]
      properties:
        email:
          type: string
          format: email
        role:
          type: string
          enum: [workspace_admin, editor, member, viewer]

    # ── Settings ──
    Setting:
      type: object
      properties:
        key:
          type: string
          example: theme
        value:
          type: string
          example: dark
        updated_at:
          type: string
          format: date-time

    UpdateSettingsRequest:
      type: object
      required: [settings]
      properties:
        settings:
          type: array
          items:
            type: object
            required: [key, value]
            properties:
              key:
                type: string
              value:
                type: string

    # ── Feature Flags ──
    FeatureFlag:
      type: object
      properties:
        id:
          type: string
          format: uuid
        key:
          type: string
          example: enable_new_dashboard
        description:
          type: string
          example: New dashboard UI
        value_type:
          type: string
          enum: [boolean, string]
        default_value:
          type: string
          example: "false"
        is_enabled:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ResolvedFeatureFlag:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
          description: Resolved value (boolean or string)
        source:
          type: string
          enum: [default, workspace_override, user_override]
          description: Where this value came from

    FeatureFlagOverride:
      type: object
      properties:
        id:
          type: string
          format: uuid
        flag_id:
          type: string
          format: uuid
        scope:
          type: string
          enum: [workspace, user]
        scope_id:
          type: string
          format: uuid
        value:
          type: string
        created_at:
          type: string
          format: date-time

    CreateFeatureFlagRequest:
      type: object
      required: [key, value_type, default_value]
      properties:
        key:
          type: string
          pattern: "^[a-z][a-z0-9_]*$"
          example: enable_new_dashboard
        description:
          type: string
          example: New dashboard UI
        value_type:
          type: string
          enum: [boolean, string]
        default_value:
          type: string
          example: "false"

    UpdateFeatureFlagRequest:
      type: object
      properties:
        description:
          type: string
        default_value:
          type: string
        is_enabled:
          type: boolean

    SetFeatureFlagOverrideRequest:
      type: object
      required: [value]
      properties:
        value:
          type: string
          description: "Boolean or string value matching the flag's value_type"

    # ── Audit Logs ──
    AuditLog:
      type: object
      properties:
        id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        actor_id:
          type: string
          format: uuid
        action:
          type: string
          enum: [create, update, delete, login, logout, invite, accept_invitation]
        resource_type:
          type: string
          example: workspace
        resource_id:
          type: string
          format: uuid
        ip_address:
          type: string
          example: 192.168.1.1
        user_agent:
          type: string
        created_at:
          type: string
          format: date-time
        changes:
          type: array
          items:
            $ref: "#/components/schemas/AuditLogChange"

    AuditLogChange:
      type: object
      properties:
        field:
          type: string
          example: name
        old_value:
          type: string
          example: Old Name
        new_value:
          type: string
          example: New Name

    PaginatedAuditLogs:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AuditLog"
        pagination:
          $ref: "#/components/schemas/Pagination"

    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 20
        total:
          type: integer
          example: 150
        total_pages:
          type: integer
          example: 8