openapi: 3.0.0
paths:
  /v1/click/sessions:
    post:
      operationId: createSession
      summary: Create a click session
      parameters: []
      responses:
        '201':
          description: Session created successfully
        '404':
          description: Template not found
      tags:
        - Click
      security:
        - bearer: []
  /v1/click/sessions/{id}:
    get:
      operationId: getSession
      summary: Get a click session
      parameters:
        - name: id
          required: true
          in: path
          description: Session ID
          schema:
            type: string
      responses:
        '200':
          description: Session details
        '404':
          description: Session not found
      tags:
        - Click
      security:
        - bearer: []
  /v1/click/sessions/{id}/complete:
    post:
      operationId: completeSession
      summary: Complete a click session
      parameters:
        - name: id
          required: true
          in: path
          description: Session ID
          schema:
            type: string
      responses:
        '200':
          description: Session completed successfully
        '404':
          description: Session not found
      tags:
        - Click
      security:
        - bearer: []
  /v1/click/evidence/{sessionId}:
    get:
      operationId: getClickEvidenceBundle
      summary: Get evidence bundle for a session
      parameters:
        - name: sessionId
          required: true
          in: path
          description: Session ID
          schema:
            type: string
      responses:
        '200':
          description: Evidence bundle details
        '404':
          description: Evidence not found
      tags:
        - Click
      security:
        - bearer: []
  /v1/click/consent/{userRef}:
    get:
      operationId: getUserConsentState
      summary: Get user consent state
      parameters:
        - name: userRef
          required: true
          in: path
          description: User reference
          schema:
            type: string
      responses:
        '200':
          description: Current consent state
      tags:
        - Click
      security:
        - bearer: []
    post:
      operationId: updateUserConsentState
      summary: Update user consent state
      parameters:
        - name: userRef
          required: true
          in: path
          description: User reference
          schema:
            type: string
      responses:
        '200':
          description: Consent updated successfully
      tags:
        - Click
      security:
        - bearer: []
  /v1/click/templates:
    get:
      operationId: findAllTemplates
      summary: List all templates
      parameters:
        - name: includeVersions
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Templates retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TemplateResponseDto'
      tags:
        - Templates
      security:
        - basic: []
    post:
      operationId: createTemplate
      summary: Create a new template
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateDto'
      responses:
        '201':
          description: Template created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseDto'
        '409':
          description: Template slug already exists
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{id}:
    get:
      operationId: findOneTemplate
      summary: Get a specific template
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: includeVersions
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Template retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseDto'
        '404':
          description: Template not found
      tags:
        - Templates
      security:
        - basic: []
    patch:
      operationId: updateTemplate
      summary: Update a template
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateDto'
      responses:
        '200':
          description: Template updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseDto'
        '404':
          description: Template not found
        '409':
          description: Template slug already exists
      tags:
        - Templates
      security:
        - basic: []
    delete:
      operationId: removeTemplate
      summary: Delete a template
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '204':
          description: Template deleted successfully
        '400':
          description: Cannot delete template with active deployments
        '404':
          description: Template not found
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{id}/stats:
    get:
      operationId: getTemplateStats
      summary: Get template statistics
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Template statistics retrieved successfully
        '404':
          description: Template not found
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{templateId}/versions:
    get:
      operationId: findAllVersions
      summary: List all versions for a template
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: includeTemplate
          required: false
          in: query
          schema:
            type: boolean
        - name: includeDeployments
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Template versions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TemplateVersionResponseDto'
        '404':
          description: Template not found
      tags:
        - Templates
      security:
        - basic: []
    post:
      operationId: createVersion
      summary: Create a new template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateVersionDto'
      responses:
        '201':
          description: Template version created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
        '404':
          description: Template not found
        '409':
          description: Version already exists for this locale
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{templateId}/versions/published:
    get:
      operationId: findPublishedVersions
      summary: List published versions for a template
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Published template versions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TemplateVersionResponseDto'
        '404':
          description: Template not found
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{templateId}/versions/{versionId}:
    get:
      operationId: findOneVersion
      summary: Get a specific template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: versionId
          required: true
          in: path
          description: Version ID
          schema:
            type: string
        - name: includeTemplate
          required: false
          in: query
          schema:
            type: boolean
        - name: includeDeployments
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Template version retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
        '404':
          description: Template or version not found
      tags:
        - Templates
      security:
        - basic: []
    patch:
      operationId: updateVersion
      summary: Update a template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: versionId
          required: true
          in: path
          description: Version ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateVersionDto'
      responses:
        '200':
          description: Template version updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
        '400':
          description: Cannot modify published versions
        '404':
          description: Template or version not found
        '409':
          description: Version already exists for this locale
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{templateId}/versions/{versionId}/publish:
    post:
      operationId: publishVersion
      summary: Publish or unpublish a template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: versionId
          required: true
          in: path
          description: Version ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishTemplateVersionDto'
      responses:
        '200':
          description: Template version published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
        '400':
          description: Cannot publish archived versions
        '404':
          description: Template or version not found
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{templateId}/versions/{versionId}/archive:
    post:
      operationId: archiveVersion
      summary: Archive a template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: versionId
          required: true
          in: path
          description: Version ID
          schema:
            type: string
      responses:
        '200':
          description: Template version archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
        '400':
          description: Cannot archive version with active deployments
        '404':
          description: Template or version not found
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/types:
    get:
      operationId: getTemplateTypes
      summary: Get available template types
      description: Returns all available template types with their configurations
      parameters: []
      responses:
        '200':
          description: List of template types with configurations
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{id}/configuration:
    get:
      operationId: getTemplateConfiguration
      summary: Get template configuration
      description: Returns template configuration including type config and policy flags
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Template configuration details
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{id}/policy-flags:
    post:
      operationId: applyPolicyFlags
      summary: Apply policy flags to template
      description: Updates template policy flags with validation
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Policy flags applied successfully
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/{id}/verification-requirements:
    get:
      operationId: getVerificationRequirements
      summary: Get template verification requirements
      description: Returns what verification methods are required for this template
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Verification requirements
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/templates/validate-content:
    post:
      operationId: validateContent
      summary: Validate template content
      description: >-
        Validates template content against type-specific rules. `type` is
        REQUIRED and identifies which validation ruleset to apply.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - content
              properties:
                type:
                  type: string
                  enum:
                    - STATIC
                    - GENERATED
                    - CONSENT
                  description: Template type to validate against
                content:
                  type: string
                  description: The template content to validate
                format:
                  type: string
                  description: Content format (defaults to `html`)
                  default: html
      responses:
        '200':
          description: Validation result (`{ valid, errors }`)
        '400':
          description: Missing required body fields (e.g. `type`)
      tags:
        - Templates
      security:
        - basic: []
  /v1/click/deployments:
    get:
      operationId: findAllDeployments
      summary: List all deployments
      parameters:
        - name: siteId
          required: false
          in: query
          description: Filter by site ID
          schema:
            type: string
        - name: environment
          required: false
          in: query
          description: Filter by environment
          schema:
            type: string
        - name: active
          required: false
          in: query
          description: Filter by active status
          schema:
            type: boolean
        - name: includeSite
          required: false
          in: query
          description: Include site details
          schema:
            type: boolean
        - name: includeTemplateVersion
          required: false
          in: query
          description: Include template version details
          schema:
            type: boolean
      responses:
        '200':
          description: Deployments retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeploymentResponseDto'
      tags:
        - Deployments
      security:
        - basic: []
    post:
      operationId: createDeployment
      summary: Create a new deployment
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentDto'
      responses:
        '201':
          description: Deployment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponseDto'
        '400':
          description: Invalid deployment data
        '404':
          description: Site or template version not found
        '409':
          description: Deployment already exists for this combination
      tags:
        - Deployments
      security:
        - basic: []
  /v1/click/deployments/domain/{domain}/active:
    get:
      operationId: findActiveByDomain
      summary: Get active deployments for a domain
      parameters:
        - name: domain
          required: true
          in: path
          description: Domain
          schema:
            type: string
        - name: environment
          required: false
          in: query
          description: Filter by environment
          schema:
            type: string
      responses:
        '200':
          description: Active deployments retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeploymentResponseDto'
      tags:
        - Deployments
      security:
        - basic: []
  /v1/click/deployments/{id}:
    get:
      operationId: findOneDeployment
      summary: Get a specific deployment
      parameters:
        - name: id
          required: true
          in: path
          description: Deployment ID
          schema:
            type: string
        - name: includeSite
          required: false
          in: query
          description: Include site details
          schema:
            type: boolean
        - name: includeTemplateVersion
          required: false
          in: query
          description: Include template version details
          schema:
            type: boolean
      responses:
        '200':
          description: Deployment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponseDto'
        '404':
          description: Deployment not found
      tags:
        - Deployments
      security:
        - basic: []
    patch:
      operationId: updateDeployment
      summary: Update a deployment
      parameters:
        - name: id
          required: true
          in: path
          description: Deployment ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDeploymentDto'
      responses:
        '200':
          description: Deployment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponseDto'
        '400':
          description: Invalid deployment data
        '404':
          description: Deployment not found
        '409':
          description: Deployment already exists for this combination
      tags:
        - Deployments
      security:
        - basic: []
    delete:
      operationId: removeDeployment
      summary: Delete a deployment
      parameters:
        - name: id
          required: true
          in: path
          description: Deployment ID
          schema:
            type: string
      responses:
        '204':
          description: Deployment deleted successfully
        '404':
          description: Deployment not found
      tags:
        - Deployments
      security:
        - basic: []
  /v1/click/deployments/domain/{domain}/deactivate:
    post:
      operationId: deactivateByPath
      summary: Deactivate deployments by path
      parameters:
        - name: domain
          required: true
          in: path
          description: Domain
          schema:
            type: string
        - name: environment
          required: true
          in: query
          description: Environment
          schema:
            type: string
        - name: path
          required: true
          in: query
          description: Path to deactivate
          schema:
            type: string
      responses:
        '200':
          description: Deployments deactivated successfully
      tags:
        - Deployments
      security:
        - basic: []
  /v1/click/analytics/dashboard:
    get:
      operationId: getDashboardMetrics
      summary: Get dashboard analytics and metrics
      parameters: []
      responses:
        '200':
          description: Dashboard metrics retrieved successfully
      tags:
        - Analytics
      security:
        - basic: []
  /v1/click/analytics/acceptance:
    get:
      operationId: getAcceptanceAnalytics
      summary: Get acceptance analytics
      parameters:
        - name: templateId
          required: true
          in: query
          schema:
            type: string
        - name: from
          required: true
          in: query
          schema:
            type: string
        - name: to
          required: true
          in: query
          schema:
            type: string
        - name: groupBy
          required: true
          in: query
          schema:
            type: string
        - name: timeRange
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Acceptance analytics retrieved successfully
      tags:
        - Analytics
      security:
        - basic: []
  /v1/click/acceptances:
    get:
      operationId: getAcceptances
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Acceptances
  /v1/click/acceptances/{id}:
    get:
      operationId: getAcceptance
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: includeEvidence
          required: true
          in: query
          schema:
            type: string
        - name: includeReceipt
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
      tags:
        - Acceptances
  /v1/click/acceptances/{id}/evidence:
    get:
      operationId: getEvidenceBundle
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
      tags:
        - Acceptances
  /v1/click/receipts/{receiptId}:
    get:
      operationId: getReceipt
      parameters:
        - name: receiptId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
      tags:
        - Acceptances
  /v1/click/evidence/retention/status:
    get:
      operationId: getRetentionStatus
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Acceptances
  /v1/click/acceptances/{id}/screenshot:
    get:
      operationId: getScreenshot
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
      tags:
        - Acceptances
  /v1/click/organization/settings:
    get:
      operationId: getSettings
      summary: Get organization settings
      description: >-
        Retrieve organization settings including retention policies, PII mode,
        webhook configuration, and default policy flags
      parameters: []
      responses:
        '200':
          description: Organization settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSettingsDto'
        '404':
          description: Organization not found
      tags:
        - Organization
      security:
        - basic: []
    patch:
      operationId: updateSettings
      summary: Update organization settings
      description: >-
        Update organization settings such as retention policies, PII mode,
        webhook configuration, and default policy flags
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationSettingsDto'
      responses:
        '200':
          description: Organization settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSettingsDto'
        '400':
          description: Invalid input data
        '404':
          description: Organization not found
      tags:
        - Organization
      security:
        - basic: []
  /v1/click/users/organization/members:
    get:
      operationId: getOrganizationMembers
      summary: Get organization members and invitations
      parameters: []
      responses:
        '200':
          description: Organization members retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationMembersResponseDto'
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/organization/invite:
    post:
      operationId: inviteUser
      summary: Invite a user to the organization
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteUserDto'
      responses:
        '201':
          description: Invitation sent successfully
        '409':
          description: User already exists or has pending invitation
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/organization/members/{userId}:
    put:
      operationId: updateMembership
      summary: Update organization membership
      parameters:
        - name: userId
          required: true
          in: path
          description: User ID to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMembershipDto'
      responses:
        '200':
          description: Membership updated successfully
        '404':
          description: Membership not found
      tags:
        - Users
      security:
        - bearer: []
    delete:
      operationId: removeMember
      summary: Remove user from organization
      parameters:
        - name: userId
          required: true
          in: path
          description: User ID to remove
          schema:
            type: string
      responses:
        '200':
          description: User removed successfully
        '400':
          description: Cannot remove last organization admin
        '404':
          description: Membership not found
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/accept-invitation:
    post:
      operationId: acceptInvitation
      summary: Accept organization invitation
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptInvitationDto'
      responses:
        '200':
          description: Invitation accepted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDto'
        '404':
          description: Invalid or expired invitation
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/organization/invitations/{invitationId}:
    delete:
      operationId: cancelInvitation
      summary: Cancel pending invitation
      parameters:
        - name: invitationId
          required: true
          in: path
          description: Invitation ID to cancel
          schema:
            type: string
      responses:
        '200':
          description: Invitation cancelled successfully
        '404':
          description: Invitation not found
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/organization/members/{userId}/capabilities:
    get:
      operationId: getUserCapabilities
      summary: Get user capabilities in organization
      parameters:
        - name: userId
          required: true
          in: path
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: User capabilities retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  capabilities:
                    type: array
                    items:
                      type: string
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/roles:
    get:
      operationId: getRoles
      summary: Get available RBAC roles and their capabilities
      parameters: []
      responses:
        '200':
          description: RBAC roles retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        description:
                          type: string
                        capabilities:
                          type: array
                          items:
                            type: string
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/{userId}/settings:
    get:
      operationId: getUserSettings
      summary: Get user settings
      parameters:
        - name: userId
          required: true
          in: path
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: User settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSettingsDto'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - bearer: []
    put:
      operationId: updateUserSettings
      summary: Update user settings
      parameters:
        - name: userId
          required: true
          in: path
          description: User ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserSettingsDto'
      responses:
        '200':
          description: User settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSettingsDto'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/{userId}/api-key/generate:
    post:
      operationId: generatePersonalApiKey
      summary: Generate personal API key for user
      parameters:
        - name: userId
          required: true
          in: path
          description: User ID
          schema:
            type: string
      responses:
        '201':
          description: Personal API key generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonalApiKeyDto'
        '404':
          description: User not found
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/users/{userId}/api-key:
    delete:
      operationId: revokePersonalApiKey
      summary: Revoke personal API key for user
      parameters:
        - name: userId
          required: true
          in: path
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: Personal API key revoked successfully
        '404':
          description: User not found
      tags:
        - Users
      security:
        - bearer: []
  /v1/click/validate/receipt:
    post:
      operationId: validateReceiptJson
      summary: Validate a cryptographic receipt
      description: Upload and verify the authenticity of a cryptographic receipt JSON file
      parameters: []
      responses:
        '200':
          description: Receipt validation completed
        '400':
          description: Invalid receipt format
      tags:
        - Validation
      security:
        - bearer: []
  /v1/click/validate/receipt/upload:
    post:
      operationId: validateReceiptFile
      summary: Validate a receipt file upload
      description: Upload a receipt.json file for verification
      parameters: []
      responses:
        '200':
          description: Receipt file validation completed
        '400':
          description: Invalid file or format
      tags:
        - Validation
      security:
        - bearer: []
  /v1/click/validate/certificate:
    post:
      operationId: generateCertificate
      summary: Generate verification certificate
      description: Generate a printable verification certificate from validation results
      parameters: []
      responses:
        '201':
          description: Certificate generated successfully
        '400':
          description: Invalid validation result
      tags:
        - Validation
      security:
        - bearer: []
  /v1/click/validate/certificate/{certificateId}:
    get:
      operationId: getCertificate
      summary: Retrieve verification certificate
      description: Get a previously generated verification certificate by ID
      parameters:
        - name: certificateId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Certificate retrieved successfully
        '404':
          description: Certificate not found
      tags:
        - Validation
      security:
        - bearer: []
  /v1/click/validate/certificate/{certificateId}/download:
    get:
      operationId: downloadCertificate
      summary: Download verification certificate as PDF
      description: Download a verification certificate in PDF format
      parameters:
        - name: certificateId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Certificate PDF downloaded
        '404':
          description: Certificate not found
      tags:
        - Validation
      security:
        - bearer: []
  /v1/click/validate/validate-and-certify:
    post:
      operationId: validateAndCertify
      summary: Validate receipt and generate certificate in one step
      description: >-
        Convenience endpoint that validates a receipt and generates a
        certificate
      parameters: []
      responses:
        '200':
          description: Receipt validated and certificate generated
        '400':
          description: Invalid receipt
      tags:
        - Validation
      security:
        - bearer: []
  /v1/click/verification/email/send:
    post:
      operationId: sendEmailVerification
      summary: Send email verification code
      parameters: []
      responses:
        '200':
          description: Verification code sent
        '400':
          description: Invalid email
      tags:
        - Verification
      security:
        - bearer: []
  /v1/click/verification/email/verify:
    post:
      operationId: verifyEmailCode
      summary: Verify email code
      parameters: []
      responses:
        '200':
          description: Email verified
        '400':
          description: Invalid code
      tags:
        - Verification
      security:
        - bearer: []
  /v1/click/verification/sms/send:
    post:
      operationId: sendSMSVerification
      summary: Send SMS verification code
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Verification
      security:
        - bearer: []
  /v1/click/verification/sms/verify:
    post:
      operationId: verifySMSCode
      summary: Verify SMS code
      parameters: []
      responses:
        '200':
          description: ''
      tags:
        - Verification
      security:
        - bearer: []
  /v1/click/config/click-defaults:
    get:
      operationId: getClickDefaults
      summary: Get Click default settings
      description: Retrieve platform-wide default settings for Click experiences
      parameters: []
      responses:
        '200':
          description: Click default settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickDefaultSettingsDto'
      tags:
        - Config
      security:
        - basic: []
    put:
      operationId: updateClickDefaults
      summary: Update Click default settings
      description: Update platform-wide default settings for Click experiences (admin only)
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClickDefaultSettingsDto'
      responses:
        '200':
          description: Click default settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickDefaultSettingsDto'
        '400':
          description: Invalid input data
        '403':
          description: Forbidden - Admin access required
      tags:
        - Config
      security:
        - basic: []
info:
  title: Click Management API
  description: >-
    The Propper Click API provides consent and clickwrap management for websites
    and applications.

    Create templates, publish versioned policies, deploy them to domains, and
    collect legally-binding acceptance records with full evidence bundles.


    ---


    ## Base URL


    `https://api.propper.ai/v1/click`


    ## Authentication


    OAuth 2.0 Bearer token:


    ```

    Authorization: Bearer <access_token>

    ```


    ## OAuth Scopes


    - `click:admin` — Full administrative access (create, update, delete)

    - `click:read` — Read-only access to templates, deployments, and acceptances


    ## Key Endpoints


    - **Templates** — Create and manage consent/clickwrap templates

    - **Template Versions** — Publish, archive, and manage versioned content

    - **Deployments** — Deploy templates to domains and control activation

    - **Acceptances** — View acceptance records and evidence bundles
  version: '1.0'
  contact:
    name: Propper Support
    url: https://propper.ai
    email: support@propper.ai
tags:
  - name: Templates
    description: Create and manage consent/clickwrap templates
  - name: Deployments
    description: Deploy templates to domains and manage activation
  - name: Click
    description: Legacy click session and consent management
  - name: Acceptances
    description: View acceptance records and evidence bundles
  - name: Analytics
    description: Dashboard metrics and acceptance analytics
  - name: Config
    description: Administrative default settings
  - name: Organization
    description: Organization settings management
  - name: Users
    description: User and member management, API keys
  - name: Validation
    description: Receipt validation and certificate generation
  - name: Verification
    description: Email and SMS verification
servers:
  - url: https://api.propper.ai
    description: Production server
security:
  - bearer: []
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: OAuth 2.0 Bearer token
    basic:
      scheme: basic
      type: http
      description: >-
        HTTP Basic authentication using an organization API key as the username
        (legacy SDK compatibility).
  schemas:
    CreateTemplateDto:
      type: object
      properties:
        name:
          type: string
          description: Template name
          example: Terms of Service
          minLength: 1
          maxLength: 255
        slug:
          type: string
          description: Template slug (URL-friendly identifier)
          example: terms-of-service
          pattern: ^[a-z0-9-]+$
        type:
          type: string
          description: Template type
          enum:
            - STATIC
            - GENERATED
            - CONSENT
          default: STATIC
        retentionDays:
          type: number
          description: Data retention period in days
          minimum: 30
          maximum: 3650
          default: 2555
        consentVersion:
          type: string
          description: Consent version
          default: '1.0'
        description:
          type: string
          description: Template description
        content:
          type: object
          description: Initial content for the template
        metadata:
          type: object
          description: Template metadata
        settings:
          type: object
          description: Additional template settings
      required:
        - name
        - slug
    TemplateResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Template ID
        orgId:
          type: string
          description: Organization ID
        name:
          type: string
          description: Template name
        slug:
          type: string
          description: Template slug
        type:
          type: string
          description: Template type
        retentionDays:
          type: number
          description: Data retention period in days
        consentVersion:
          type: string
          description: Consent version
        settings:
          type: object
          description: Template settings
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
        versions:
          type: array
          description: Template versions (only included when explicitly requested)
          items:
            type: object
      required:
        - id
        - orgId
        - name
        - slug
        - type
        - retentionDays
        - consentVersion
        - settings
        - createdAt
        - updatedAt
    UpdateTemplateDto:
      type: object
      properties:
        name:
          type: string
          description: Template name
          example: Terms of Service
          minLength: 1
          maxLength: 255
        slug:
          type: string
          description: Template slug (URL-friendly identifier)
          example: terms-of-service
          pattern: ^[a-z0-9-]+$
        type:
          type: string
          description: Template type
          enum:
            - STATIC
            - GENERATED
            - CONSENT
          default: STATIC
        retentionDays:
          type: number
          description: Data retention period in days
          minimum: 30
          maximum: 3650
          default: 2555
        consentVersion:
          type: string
          description: Consent version
          default: '1.0'
        description:
          type: string
          description: Template description
        content:
          type: object
          description: Initial content for the template
        metadata:
          type: object
          description: Template metadata
        settings:
          type: object
          description: Additional template settings
    TemplateVersionResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Version ID
        templateId:
          type: string
          description: Template ID
        version:
          type: string
          description: Semantic version number
        title:
          type: string
          description: Version title
        content:
          type: string
          description: Template content
        locale:
          type: string
          description: Content locale
        format:
          type: string
          description: Content format
        checksum:
          type: string
          description: Content checksum
        metadata:
          type: object
          description: Additional metadata
        published:
          type: boolean
          description: Whether version is published
        archivedAt:
          format: date-time
          type: string
          description: Archive timestamp
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
        template:
          type: object
          description: Template details (only included when explicitly requested)
        deployments:
          type: array
          description: >-
            Deployments using this version (only included when explicitly
            requested)
          items:
            type: object
      required:
        - id
        - templateId
        - version
        - title
        - content
        - locale
        - format
        - checksum
        - metadata
        - published
        - createdAt
        - updatedAt
    CreateTemplateVersionDto:
      type: object
      properties:
        version:
          type: string
          description: Semantic version number
          example: 1.0.0
          default: 1.0.0
        title:
          type: string
          description: Version title
          example: Terms of Service v1.0
          minLength: 1
          maxLength: 255
        content:
          type: string
          description: Template content
          example: <h1>Terms of Service</h1><p>These terms govern...</p>
        locale:
          type: string
          description: Content locale
          example: en
          default: en
        format:
          type: string
          description: Content format
          enum:
            - html
            - markdown
            - pdf
            - docx
            - pdf_url
          default: html
        metadata:
          type: object
          description: Additional metadata
        published:
          type: boolean
          description: Whether to publish immediately
          default: false
      required:
        - title
        - content
    UpdateTemplateVersionDto:
      type: object
      properties:
        version:
          type: string
          description: Semantic version number
          example: 1.0.0
          default: 1.0.0
        title:
          type: string
          description: Version title
          example: Terms of Service v1.0
          minLength: 1
          maxLength: 255
        content:
          type: string
          description: Template content
          example: <h1>Terms of Service</h1><p>These terms govern...</p>
        locale:
          type: string
          description: Content locale
          example: en
          default: en
        format:
          type: string
          description: Content format
          enum:
            - html
            - markdown
            - pdf
            - docx
            - pdf_url
          default: html
        metadata:
          type: object
          description: Additional metadata
        published:
          type: boolean
          description: Whether to publish immediately
          default: false
    PublishTemplateVersionDto:
      type: object
      properties:
        published:
          type: boolean
          description: Whether to publish the version
          default: true
    DeploymentResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Deployment ID
        domain:
          type: string
          description: Domain
        templateVersionId:
          type: string
          description: Template version ID
        environment:
          type: string
          description: Deployment environment
        path:
          type: string
          description: URL path
        variant:
          type: string
          description: A/B test variant
        active:
          type: boolean
          description: Whether deployment is active
        priority:
          type: number
          description: Deployment priority
        startAt:
          format: date-time
          type: string
          description: Start timestamp
        endAt:
          format: date-time
          type: string
          description: End timestamp
        policyFlags:
          type: object
          description: Policy flags override
        settings:
          type: object
          description: Deployment-specific settings
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
        templateVersion:
          type: object
          description: Template version details (only included when explicitly requested)
      required:
        - id
        - domain
        - templateVersionId
        - environment
        - path
        - active
        - priority
        - startAt
        - createdAt
        - updatedAt
    CreateDeploymentDto:
      type: object
      properties:
        domain:
          type: string
          description: Domain where template will be deployed
          example: example.com
        templateVersionId:
          type: string
          description: Template version ID to deploy
          format: uuid
        environment:
          type: string
          description: Deployment environment
          enum:
            - production
            - staging
            - development
          default: production
        path:
          type: string
          description: URL path where template will be active
          example: /
          default: /
        variant:
          type: string
          description: A/B test variant identifier
          example: variant-a
        active:
          type: boolean
          description: Whether deployment is active
          default: true
        priority:
          type: number
          description: Deployment priority (higher numbers take precedence)
          minimum: 0
          maximum: 1000
          default: 0
        startAt:
          type: string
          description: When deployment becomes active (ISO 8601 date)
          example: '2024-01-15T10:00:00.000Z'
        endAt:
          type: string
          description: When deployment expires (ISO 8601 date)
          example: '2024-12-31T23:59:59.999Z'
        policyFlags:
          type: object
          description: Policy flags override for this deployment
          properties:
            requireScroll:
              type: boolean
              description: Require user to scroll through content
            blockUntilAssent:
              type: boolean
              description: Block interaction until consent is given
            doubleCheckbox:
              type: boolean
              description: Require double checkbox confirmation
        settings:
          type: object
          description: Deployment-specific settings and overrides
      required:
        - domain
        - templateVersionId
    UpdateDeploymentDto:
      type: object
      properties:
        domain:
          type: string
          description: Domain where template will be deployed
          example: example.com
        templateVersionId:
          type: string
          description: Template version ID to deploy
          format: uuid
        environment:
          type: string
          description: Deployment environment
          enum:
            - production
            - staging
            - development
          default: production
        path:
          type: string
          description: URL path where template will be active
          example: /
          default: /
        variant:
          type: string
          description: A/B test variant identifier
          example: variant-a
        active:
          type: boolean
          description: Whether deployment is active
          default: true
        priority:
          type: number
          description: Deployment priority (higher numbers take precedence)
          minimum: 0
          maximum: 1000
          default: 0
        startAt:
          type: string
          description: When deployment becomes active (ISO 8601 date)
          example: '2024-01-15T10:00:00.000Z'
        endAt:
          type: string
          description: When deployment expires (ISO 8601 date)
          example: '2024-12-31T23:59:59.999Z'
        policyFlags:
          type: object
          description: Policy flags override for this deployment
          properties:
            requireScroll:
              type: boolean
              description: Require user to scroll through content
            blockUntilAssent:
              type: boolean
              description: Block interaction until consent is given
            doubleCheckbox:
              type: boolean
              description: Require double checkbox confirmation
        settings:
          type: object
          description: Deployment-specific settings and overrides
    PolicyFlagsDto:
      type: object
      properties:
        requireScroll:
          type: boolean
          description: Require users to scroll before accepting
        blockUntilAssent:
          type: boolean
          description: Block UI until agreement is accepted
        doubleCheckbox:
          type: boolean
          description: Require two separate checkbox confirmations
        showAcceptanceDate:
          type: boolean
          description: Show acceptance date in UI
        allowDecline:
          type: boolean
          description: Allow users to decline
        requireExplicitConsent:
          type: boolean
          description: Require explicit consent confirmation
      required:
        - requireScroll
        - blockUntilAssent
        - doubleCheckbox
        - showAcceptanceDate
        - allowDecline
        - requireExplicitConsent
    TemplateSettingsDto:
      type: object
      properties:
        defaultConsentMethod:
          type: string
          description: Default consent method
          enum:
            - CHECKBOX
            - CLICK
            - SCROLL
            - SIGNIN_WRAP
        allowedConsentMethods:
          description: Allowed consent methods
          type: array
          items:
            type: string
        displayMode:
          type: string
          description: Display mode
          enum:
            - modal
            - inline
            - banner
            - wall
        allowedRenderModes:
          description: Allowed render modes
          type: array
          items:
            type: string
        requireIdentity:
          type: boolean
          description: Whether identity is required
        identityMethods:
          description: Available identity methods
          type: array
          items:
            type: string
        minimumAge:
          type: number
          description: Minimum age requirement
        policyFlags:
          description: Policy flags configuration
          allOf:
            - $ref: '#/components/schemas/PolicyFlagsDto'
        customCss:
          type: string
          description: Custom CSS styles
        customJavascript:
          type: string
          description: Custom JavaScript code
        metadata:
          type: object
          description: Additional metadata
      required:
        - defaultConsentMethod
        - allowedConsentMethods
        - displayMode
        - allowedRenderModes
        - requireIdentity
        - identityMethods
        - policyFlags
    DefaultTemplateSettingsDto:
      type: object
      properties:
        clickwrap:
          description: Default settings for clickwrap templates
          allOf:
            - $ref: '#/components/schemas/TemplateSettingsDto'
        terms:
          description: Default settings for terms templates
          allOf:
            - $ref: '#/components/schemas/TemplateSettingsDto'
        privacy:
          description: Default settings for privacy templates
          allOf:
            - $ref: '#/components/schemas/TemplateSettingsDto'
      required:
        - clickwrap
        - terms
        - privacy
    FeatureFlagsDto:
      type: object
      properties:
        webhooks:
          type: boolean
          description: Enable webhook functionality
        multiLocale:
          type: boolean
          description: Enable multi-locale support
        abTesting:
          type: boolean
          description: Enable A/B testing features
      required:
        - webhooks
        - multiLocale
        - abTesting
    WebhookSettingsDto:
      type: object
      properties:
        events:
          description: Webhook event types to send
          type: array
          items:
            type: string
      required:
        - events
    ComplianceSettingsDto:
      type: object
      properties:
        evidenceRetentionDays:
          type: number
          description: Evidence retention period in days
        immutableStorage:
          type: boolean
          description: Enable immutable storage (WORM)
        auditLogRetentionDays:
          type: number
          description: Audit log retention period in days
        requireApprovalWorkflow:
          type: boolean
          description: Require approval workflow for publishing
      required:
        - evidenceRetentionDays
        - immutableStorage
        - auditLogRetentionDays
        - requireApprovalWorkflow
    OrganizationSettingsDto:
      type: object
      properties:
        id:
          type: string
          description: Organization ID
        name:
          type: string
          description: Organization name
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        defaultRetentionDays:
          type: number
          description: Default evidence retention period in days
          example: 2555
        piiMode:
          type: string
          description: PII collection mode
          enum:
            - Minimal
            - Balanced
            - Full
          example: Balanced
        webhookUrl:
          type: string
          description: Webhook URL for notifications
        webhookSecretLast4:
          type: string
          nullable: true
          description: >-
            Last 4 characters of the configured webhook signing secret. The full
            secret is never returned by this endpoint — rotate it via the admin
            rotate flow to obtain a new value.
          example: a1b2
        webhookEnabled:
          type: boolean
          description: Whether webhooks are enabled
          example: false
        defaultTemplateSettings:
          description: Default template settings by type
          allOf:
            - $ref: '#/components/schemas/DefaultTemplateSettingsDto'
        features:
          description: Feature flags configuration
          allOf:
            - $ref: '#/components/schemas/FeatureFlagsDto'
        webhookSettings:
          description: Webhook configuration
          allOf:
            - $ref: '#/components/schemas/WebhookSettingsDto'
        complianceSettings:
          description: Compliance and governance settings
          allOf:
            - $ref: '#/components/schemas/ComplianceSettingsDto'
      required:
        - id
        - name
        - createdAt
        - defaultRetentionDays
        - piiMode
        - webhookEnabled
        - defaultTemplateSettings
        - features
        - webhookSettings
        - complianceSettings
    UpdatePolicyFlagsDto:
      type: object
      properties:
        requireScroll:
          type: boolean
          description: Require users to scroll before accepting
        blockUntilAssent:
          type: boolean
          description: Block UI until agreement is accepted
        doubleCheckbox:
          type: boolean
          description: Require two separate checkbox confirmations
        showAcceptanceDate:
          type: boolean
          description: Show acceptance date in UI
        allowDecline:
          type: boolean
          description: Allow users to decline
        requireExplicitConsent:
          type: boolean
          description: Require explicit consent confirmation
    UpdateTemplateSettingsDto:
      type: object
      properties:
        defaultConsentMethod:
          type: string
          description: Default consent method
          enum:
            - CHECKBOX
            - CLICK
            - SCROLL
            - SIGNIN_WRAP
        allowedConsentMethods:
          description: Allowed consent methods
          type: array
          items:
            type: string
        displayMode:
          type: string
          description: Display mode
          enum:
            - modal
            - inline
            - banner
            - wall
        allowedRenderModes:
          description: Allowed render modes
          type: array
          items:
            type: string
        requireIdentity:
          type: boolean
          description: Whether identity is required
        identityMethods:
          description: Available identity methods
          type: array
          items:
            type: string
        minimumAge:
          type: number
          description: Minimum age requirement
        policyFlags:
          description: Policy flags configuration
          allOf:
            - $ref: '#/components/schemas/UpdatePolicyFlagsDto'
        customCss:
          type: string
          description: Custom CSS styles
        customJavascript:
          type: string
          description: Custom JavaScript code
        metadata:
          type: object
          description: Additional metadata
    UpdateDefaultTemplateSettingsDto:
      type: object
      properties:
        clickwrap:
          description: Default settings for clickwrap templates
          allOf:
            - $ref: '#/components/schemas/UpdateTemplateSettingsDto'
        terms:
          description: Default settings for terms templates
          allOf:
            - $ref: '#/components/schemas/UpdateTemplateSettingsDto'
        privacy:
          description: Default settings for privacy templates
          allOf:
            - $ref: '#/components/schemas/UpdateTemplateSettingsDto'
    UpdateOrganizationSettingsDto:
      type: object
      properties:
        name:
          type: string
          description: Organization name
        defaultRetentionDays:
          type: number
          description: Default evidence retention period in days
          minimum: 365
          maximum: 3650
        piiMode:
          type: string
          description: PII collection mode
          enum:
            - Minimal
            - Balanced
            - Full
        webhookUrl:
          type: string
          description: Webhook URL for notifications
        webhookSecret:
          type: string
          description: Webhook signing secret
        webhookEnabled:
          type: boolean
          description: Whether webhooks are enabled
        defaultTemplateSettings:
          description: Default template settings by type
          allOf:
            - $ref: '#/components/schemas/UpdateDefaultTemplateSettingsDto'
        features:
          description: Feature flags configuration
          allOf:
            - $ref: '#/components/schemas/FeatureFlagsDto'
        webhookSettings:
          description: Webhook configuration
          allOf:
            - $ref: '#/components/schemas/WebhookSettingsDto'
        complianceSettings:
          description: Compliance and governance settings
          allOf:
            - $ref: '#/components/schemas/ComplianceSettingsDto'
    AccessScopeDto:
      type: object
      properties:
        environments:
          type: array
          description: Environments user can access
          items:
            type: string
            enum:
              - PROD
              - STAGE
              - DEV
        sites:
          description: Site IDs user can access
          type: array
          items:
            type: string
        resources:
          description: Resource-specific access
          type: array
          items:
            type: string
    OrganizationMembershipDto:
      type: object
      properties:
        id:
          type: string
          description: Membership ID
        orgId:
          type: string
          description: Organization ID
        userId:
          type: string
          description: User ID
        role:
          type: string
          description: User role in the organization
          enum:
            - ORG_ADMIN
            - LEGAL_AUTHOR
            - COMPLIANCE_APPROVER
            - PUBLISHER
            - SECURITY_ADMIN
            - DEVELOPER_INTEGRATION
            - ANALYST
            - SUPPORT_AUDITOR
            - BILLING_ADMIN
        scope:
          description: Access scope restrictions
          allOf:
            - $ref: '#/components/schemas/AccessScopeDto'
        status:
          type: string
          description: Membership status
          enum:
            - ACTIVE
            - INVITED
            - SUSPENDED
        joinedAt:
          format: date-time
          type: string
          description: Date when user joined
        expiresAt:
          format: date-time
          type: string
          description: Date when membership expires
        invitedBy:
          type: string
          description: ID of user who invited this member
        invitedAt:
          format: date-time
          type: string
          description: Date when user was invited
        createdAt:
          format: date-time
          type: string
          description: Date when membership was created
        updatedAt:
          format: date-time
          type: string
          description: Date when membership was last updated
      required:
        - id
        - orgId
        - userId
        - role
        - scope
        - status
        - joinedAt
        - createdAt
        - updatedAt
    UserDto:
      type: object
      properties:
        id:
          type: string
          description: User ID
        email:
          type: string
          description: User email address
        name:
          type: string
          description: User full name
        isActive:
          type: boolean
          description: Whether user account is active
        lastLoginAt:
          format: date-time
          type: string
          description: Last login timestamp
        createdAt:
          format: date-time
          type: string
          description: User creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: User last update timestamp
        memberships:
          description: User organization memberships
          type: array
          items:
            $ref: '#/components/schemas/OrganizationMembershipDto'
      required:
        - id
        - email
        - name
        - isActive
        - createdAt
        - updatedAt
        - memberships
    UserInvitationDto:
      type: object
      properties:
        id:
          type: string
          description: Invitation ID
        email:
          type: string
          description: Invited email address
        orgId:
          type: string
          description: Organization ID
        role:
          type: string
          description: Role for the invited user
          enum:
            - ORG_ADMIN
            - LEGAL_AUTHOR
            - COMPLIANCE_APPROVER
            - PUBLISHER
            - SECURITY_ADMIN
            - DEVELOPER_INTEGRATION
            - ANALYST
            - SUPPORT_AUDITOR
            - BILLING_ADMIN
        invitedBy:
          type: string
          description: ID of user who sent the invitation
        scope:
          description: Access scope for the invited user
          allOf:
            - $ref: '#/components/schemas/AccessScopeDto'
        token:
          type: string
          description: Invitation token
        status:
          type: string
          description: Invitation status
        expiresAt:
          format: date-time
          type: string
          description: Date when invitation expires
        acceptedAt:
          format: date-time
          type: string
          description: Date when invitation was accepted
        createdAt:
          format: date-time
          type: string
          description: Date when invitation was created
      required:
        - id
        - email
        - orgId
        - role
        - invitedBy
        - scope
        - token
        - status
        - expiresAt
        - createdAt
    OrganizationMembersResponseDto:
      type: object
      properties:
        members:
          description: List of organization members
          type: array
          items:
            $ref: '#/components/schemas/UserDto'
        invitations:
          description: List of pending invitations
          type: array
          items:
            $ref: '#/components/schemas/UserInvitationDto'
        total:
          type: number
          description: Total count of members
        activeMembers:
          type: number
          description: Count of active members
        pendingInvitations:
          type: number
          description: Count of pending invitations
      required:
        - members
        - invitations
        - total
        - activeMembers
        - pendingInvitations
    InviteUserDto:
      type: object
      properties:
        email:
          type: string
          description: Email address to invite
        role:
          type: string
          description: Role to assign to the invited user
          enum:
            - ORG_ADMIN
            - LEGAL_AUTHOR
            - COMPLIANCE_APPROVER
            - PUBLISHER
            - SECURITY_ADMIN
            - DEVELOPER_INTEGRATION
            - ANALYST
            - SUPPORT_AUDITOR
            - BILLING_ADMIN
        scope:
          description: Access scope for the invited user
          allOf:
            - $ref: '#/components/schemas/AccessScopeDto'
        expiresAt:
          format: date-time
          type: string
          description: Expiration date for time-bounded access
      required:
        - email
        - role
    UpdateMembershipDto:
      type: object
      properties:
        role:
          type: string
          description: New role for the user
          enum:
            - ORG_ADMIN
            - LEGAL_AUTHOR
            - COMPLIANCE_APPROVER
            - PUBLISHER
            - SECURITY_ADMIN
            - DEVELOPER_INTEGRATION
            - ANALYST
            - SUPPORT_AUDITOR
            - BILLING_ADMIN
        scope:
          description: New access scope
          allOf:
            - $ref: '#/components/schemas/AccessScopeDto'
        status:
          type: string
          description: New membership status
          enum:
            - ACTIVE
            - INVITED
            - SUSPENDED
        expiresAt:
          format: date-time
          type: string
          description: New expiration date
    AcceptInvitationDto:
      type: object
      properties:
        token:
          type: string
          description: Invitation token
        name:
          type: string
          description: User full name
        password:
          type: string
          description: User password (if not using SSO)
      required:
        - token
        - name
    EmailNotificationsDto:
      type: object
      properties:
        acceptances:
          type: boolean
          description: Receive notifications for acceptances
        deployments:
          type: boolean
          description: Receive notifications for deployments
        systemUpdates:
          type: boolean
          description: Receive system update notifications
        weeklyReports:
          type: boolean
          description: Receive weekly reports
      required:
        - acceptances
        - deployments
        - systemUpdates
        - weeklyReports
    UserSettingsDto:
      type: object
      properties:
        userId:
          type: string
          description: User ID
        timezone:
          type: string
          description: User timezone
          example: UTC
        language:
          type: string
          description: User language preference
          example: en
        theme:
          type: string
          description: UI theme preference
          enum:
            - light
            - dark
            - system
        emailNotifications:
          description: Email notification preferences
          allOf:
            - $ref: '#/components/schemas/EmailNotificationsDto'
        defaultDashboardView:
          type: string
          description: Default dashboard view
          enum:
            - overview
            - templates
            - evidence
            - analytics
        itemsPerPage:
          type: number
          description: Items per page in lists
          example: 25
        twoFactorEnabled:
          type: boolean
          description: Whether two-factor authentication is enabled
        sessionTimeout:
          type: number
          description: Session timeout in minutes
          example: 480
        personalApiKey:
          type: string
          description: Personal API key (masked)
        personalApiKeyId:
          type: string
          description: Personal API key ID
        apiKeyCreatedAt:
          format: date-time
          type: string
          description: API key creation timestamp
        apiKeyExpiresAt:
          format: date-time
          type: string
          description: API key expiration timestamp
        createdAt:
          format: date-time
          type: string
          description: Settings creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Settings last update timestamp
      required:
        - userId
        - timezone
        - language
        - theme
        - emailNotifications
        - defaultDashboardView
        - itemsPerPage
        - twoFactorEnabled
        - sessionTimeout
        - createdAt
        - updatedAt
    UpdateUserSettingsDto:
      type: object
      properties:
        timezone:
          type: string
          description: User timezone
        language:
          type: string
          description: User language preference
        theme:
          type: string
          description: UI theme preference
          enum:
            - light
            - dark
            - system
        emailNotifications:
          description: Email notification preferences
          allOf:
            - $ref: '#/components/schemas/EmailNotificationsDto'
        defaultDashboardView:
          type: string
          description: Default dashboard view
          enum:
            - overview
            - templates
            - evidence
            - analytics
        itemsPerPage:
          type: number
          description: Items per page in lists
        twoFactorEnabled:
          type: boolean
          description: Whether two-factor authentication is enabled
        sessionTimeout:
          type: number
          description: Session timeout in minutes
    PersonalApiKeyDto:
      type: object
      properties:
        apiKey:
          type: string
          description: Generated API key
        keyId:
          type: string
          description: API key ID for reference
        createdAt:
          format: date-time
          type: string
          description: Key creation timestamp
        expiresAt:
          format: date-time
          type: string
          description: Key expiration timestamp
      required:
        - apiKey
        - keyId
        - createdAt
    ClickDefaultSettingsDto:
      type: object
      properties:
        policyFlags:
          type: object
          description: Policy flags for Click experiences
          example:
            requireScroll: false
            blockUntilAssent: true
            doubleCheckbox: false
            showAcceptanceDate: true
            allowDecline: true
            requireExplicitConsent: true
        defaultConsentMethod:
          type: string
          description: Default consent method
          example: CLICK
        allowedConsentMethods:
          description: Allowed consent methods
          example:
            - CLICK
            - CHECKBOX
          type: array
          items:
            type: string
        displayMode:
          type: string
          description: Display mode for Click experiences
          example: modal
        requireIdentity:
          type: boolean
          description: Whether to require identity verification
          example: false
        identityMethods:
          description: Available identity verification methods
          example: []
          type: array
          items:
            type: string
        acceptButtonText:
          type: string
          description: Text for accept button
          example: I Accept
        declineButtonText:
          type: string
          description: Text for decline button
          example: I Decline
        scrollPercentage:
          type: number
          description: Required scroll percentage before enabling accept
          example: 80
        timeout:
          type: number
          description: Session timeout in seconds
          example: 300
        showProgressBar:
          type: boolean
          description: Whether to show progress bar
          example: true
        enableAnalytics:
          type: boolean
          description: Whether to enable analytics tracking
          example: true
      required:
        - policyFlags
        - defaultConsentMethod
        - allowedConsentMethods
        - displayMode
        - requireIdentity
        - identityMethods
        - acceptButtonText
        - declineButtonText
        - scrollPercentage
        - timeout
        - showProgressBar
        - enableAnalytics
