Cayra Client API

openapi: 3.2.0
info:
  title: Cayra License Server Client API
  description: '# Cayra Chat Agent - License Management Server


    Centralized license management for on-premise deployments.


    ## Features


    - 🔑 License key generation (installation, update, trial)

    - ⏰ Dynamic expiry management (extend/shorten licenses)

    - 🔄 Activation tracking and monitoring

    - 💓 Heartbeat mechanism (1-hour intervals)

    - 📊 Audit logging for compliance

    - 🔐 JWT tokens with RSA-4096 encryption


    ## API Categories


    ### Admin Endpoints (Requires API Key)

    Manage licenses, view activations, update expiry dates.


    ### Client Endpoints (Public)

    Activate licenses, send heartbeats, check status.


    ## Authentication


    Admin endpoints require API key in header:

    ```

    X-Admin-API-Key: your-admin-key-here

    ```


    ## Security


    - 🔒 RSA-4096 asymmetric encryption

    - 🔐 JWT tokens for offline validation

    - 📝 Complete audit trail

    - 🛡️ Rate limiting (Phase 6)'
  contact:
    name: Cayra AI Team
    email: support@cayra.ai
  license:
    name: Proprietary
  version: 1.0.0
tags:
- name: Client
paths:
  /api/v1/licenses/workspace/summary:
    get:
      tags:
      - Client
      summary: Get Workspace Summary From License
      description: Return dashboard setup summary for a license-key scoped deployment.
      operationId: get_workspace_summary_from_license_api_v1_licenses_workspace_summary_get
      parameters:
      - name: license_key
        in: query
        required: true
        schema:
          type: string
          title: License Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfServiceWorkspaceSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Client
      summary: Update Workspace Summary From License
      description: Update editable dashboard summary fields from a cloud instance.
      operationId: update_workspace_summary_from_license_api_v1_licenses_workspace_summary_patch
      parameters:
      - name: license_key
        in: query
        required: true
        schema:
          type: string
          title: License Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfServiceWorkspaceSummaryUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfServiceWorkspaceSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/licenses/workspace/deployment:
    get:
      tags:
      - Client
      summary: Get Workspace Deployment From License
      description: Return the active deployment, including public IP, for a license key.
      operationId: get_workspace_deployment_from_license_api_v1_licenses_workspace_deployment_get
      parameters:
      - name: license_key
        in: query
        required: true
        schema:
          type: string
          title: License Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/SelfServiceDeploymentResponse'
                - type: 'null'
                title: Response Get Workspace Deployment From License Api V1 Licenses Workspace Deployment Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/licenses/activate:
    post:
      tags:
      - Client
      summary: Activate License
      description: 'Activate license on customer''s on-premise server.


        This is called once during installation. Returns JWT token

        for offline validation.


        Args:

        request: Activation request with license key and machine info

        db: Database session

        jwt_handler: JWT handler


        Returns:

        ActivationResponse with token and configuration


        Raises:

        HTTPException 404: License not found

        HTTPException 403: License invalid (expired/revoked/max activations)'
      operationId: activate_license_api_v1_licenses_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivationResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/licenses/heartbeat:
    post:
      tags:
      - Client
      summary: License Heartbeat
      description: 'License heartbeat check (called every 1 hour by license agent).


        Returns current license status and any expiry updates.


        Args:

        request: Heartbeat request with license key and metrics

        db: Database session


        Returns:

        HeartbeatResponse with license status


        Raises:

        HTTPException 404: License or activation not found

        HTTPException 403: License expired or revoked'
      operationId: license_heartbeat_api_v1_licenses_heartbeat_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/licenses/status:
    get:
      tags:
      - Client
      summary: Get License Status
      description: 'Check license status (public endpoint, no authentication).


        Returns basic license validity information.


        Args:

        license_key: License key to check

        db: Database session


        Returns:

        LicenseStatusResponse with status info


        Raises:

        HTTPException 404: License not found'
      operationId: get_license_status_api_v1_licenses_status_get
      parameters:
      - name: license_key
        in: query
        required: true
        schema:
          type: string
          title: License Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/licenses/redirect/consume:
    post:
      tags:
      - Client
      summary: Consume Redirect Token
      description: Resolve a short-lived dashboard redirect token into license-backed login data.
      operationId: consume_redirect_token_api_v1_licenses_redirect_consume_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedirectTokenConsumeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedirectTokenConsumeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/licenses/workspace/reset:
    post:
      tags:
      - Client
      summary: Reset Workspace From License
      description: Reset self-service workspace by license key for on-prem admin UI flows.
      operationId: reset_workspace_from_license_api_v1_licenses_workspace_reset_post
      parameters:
      - name: license_key
        in: query
        required: true
        schema:
          type: string
          title: License Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SelfServiceWorkspaceResetRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SelfServiceWorkspaceResetResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/downloads/installer:
    post:
      tags:
      - Client
      summary: Download Installer
      description: Stream installer artifact for a valid license key.
      operationId: download_installer_api_v1_downloads_installer_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SelfServiceWorkspaceSummaryResponse:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        email:
          anyOf:
          - type: string
            format: email
          - type: 'null'
          title: Email
        phone_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Phone Number
        locale:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Avatar Url
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
        team_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Size
        package_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Package Id
        package_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Package Name
        package_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Package Code
        package_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Package Description
        email_locked:
          type: boolean
          title: Email Locked
          default: false
        phone_locked:
          type: boolean
          title: Phone Locked
          default: false
      type: object
      title: SelfServiceWorkspaceSummaryResponse
    CloudProviderEnum:
      type: string
      enum:
      - aws
      - azure
      title: CloudProviderEnum
    HeartbeatRequest:
      properties:
        license_key:
          type: string
          title: License Key
          description: License key
        machine_id:
          type: string
          title: Machine Id
          description: Machine identifier
        system_status:
          anyOf:
          - type: object
          - type: 'null'
          title: System Status
          description: Current system metrics
          example:
            cpu_usage: 45.2
            disk_usage: 52.1
            ram_usage: 68.5
        service_status:
          anyOf:
          - type: object
          - type: 'null'
          title: Service Status
          description: Service health status
          example:
            api_server: running
            postgres: running
      type: object
      required:
      - license_key
      - machine_id
      title: HeartbeatRequest
      description: Request model for license heartbeat
    ActivationResponse:
      properties:
        success:
          type: boolean
          title: Success
        activation_id:
          type: string
          title: Activation Id
        license_token:
          type: string
          title: License Token
          description: JWT token for offline validation
        expires_at:
          type: string
          format: date-time
          title: Expires At
        features:
          type: object
          title: Features
        limits:
          type: object
          title: Limits
        public_key:
          type: string
          title: Public Key
          description: RSA public key for token verification
      type: object
      required:
      - success
      - activation_id
      - license_token
      - expires_at
      - features
      - limits
      - public_key
      title: ActivationResponse
      description: Response model for license activation
    SelfServiceDeploymentResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        company_id:
          type: string
          format: uuid
          title: Company Id
        subdomain:
          type: string
          title: Subdomain
        status:
          $ref: '#/components/schemas/DeploymentStatusEnum'
        provider:
          $ref: '#/components/schemas/CloudProviderEnum'
        public_url:
          type: string
          title: Public Url
        public_ip:
          anyOf:
          - type: string
          - type: 'null'
          title: Public Ip
        instance_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance Type
        region:
          anyOf:
          - type: string
          - type: 'null'
          title: Region
        product_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Product Version
        deployed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deployed At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - company_id
      - subdomain
      - status
      - provider
      - public_url
      - public_ip
      - instance_type
      - region
      - product_version
      - deployed_at
      - created_at
      title: SelfServiceDeploymentResponse
    SelfServiceWorkspaceResetRequest:
      properties:
        reason:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Reason
      type: object
      title: SelfServiceWorkspaceResetRequest
    LicenseStatusResponse:
      properties:
        license_id:
          type: string
          format: uuid
          title: License Id
        is_valid:
          type: boolean
          title: Is Valid
        is_active:
          type: boolean
          title: Is Active
        is_expired:
          type: boolean
          title: Is Expired
        is_revoked:
          type: boolean
          title: Is Revoked
        expires_at:
          type: string
          format: date-time
          title: Expires At
        current_activations:
          type: integer
          title: Current Activations
        max_activations:
          type: integer
          title: Max Activations
        features:
          type: object
          title: Features
        limits:
          type: object
          title: Limits
      type: object
      required:
      - license_id
      - is_valid
      - is_active
      - is_expired
      - is_revoked
      - expires_at
      - current_activations
      - max_activations
      title: LicenseStatusResponse
      description: Response model for license status check
    DownloadRequest:
      properties:
        license_key:
          type: string
          title: License Key
          description: License key
        version:
          type: string
          title: Version
          description: Product version to download
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          description: Optional cloud provider for artifact backend selection
        components:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Components
          description: 'Specific components to download (default: all)'
      type: object
      required:
      - license_key
      - version
      title: DownloadRequest
      description: Request model for installer download
    RedirectTokenConsumeRequest:
      properties:
        token:
          type: string
          minLength: 1
          title: Token
      type: object
      required:
      - token
      title: RedirectTokenConsumeRequest
    HeartbeatResponse:
      properties:
        is_valid:
          type: boolean
          title: Is Valid
          description: License validity status
        current_expiry:
          type: string
          title: Current Expiry
          description: Current expiry datetime (ISO format)
        expires_in_seconds:
          type: integer
          title: Expires In Seconds
          description: Seconds until expiry
        should_shutdown:
          type: boolean
          title: Should Shutdown
          description: Should system shutdown
        expiry_updated:
          type: boolean
          title: Expiry Updated
          description: Expiry date was updated
        features:
          type: object
          title: Features
          description: Enabled features
        limits:
          type: object
          title: Limits
          description: Usage limits
        message:
          type: string
          title: Message
          description: Human-readable message
        push_config:
          anyOf:
          - type: object
          - type: 'null'
          title: Push Config
          description: FCM push notification config to distribute to customer VMs
      type: object
      required:
      - is_valid
      - current_expiry
      - expires_in_seconds
      - should_shutdown
      - expiry_updated
      - features
      - limits
      - message
      title: HeartbeatResponse
      description: Response model for license heartbeat
    SelfServiceWorkspaceSummaryUpdateRequest:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Name
        email:
          anyOf:
          - type: string
            format: email
          - type: 'null'
          title: Email
        phone_number:
          anyOf:
          - type: string
            maxLength: 50
            minLength: 1
          - type: 'null'
          title: Phone Number
        company_name:
          anyOf:
          - type: string
            maxLength: 255
            minLength: 1
          - type: 'null'
          title: Company Name
        team_size:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Team Size
      type: object
      title: SelfServiceWorkspaceSummaryUpdateRequest
    SelfServiceWorkspaceStateResponse:
      properties:
        status:
          type: string
          title: Status
        resume_step:
          type: string
          title: Resume Step
        allowed_back_step:
          anyOf:
          - type: string
          - type: 'null'
          title: Allowed Back Step
        welcome_required:
          type: boolean
          title: Welcome Required
          default: false
        welcome_acknowledged:
          type: boolean
          title: Welcome Acknowledged
          default: false
        database_private_declared:
          type: boolean
          title: Database Private Declared
          default: false
        pre_provision_db_access_acknowledged:
          type: boolean
          title: Pre Provision Db Access Acknowledged
          default: false
        post_provision_confirmation_required:
          type: boolean
          title: Post Provision Confirmation Required
          default: false
        post_provision_confirmation_completed:
          type: boolean
          title: Post Provision Confirmation Completed
          default: false
        license_server_allowlist_host:
          anyOf:
          - type: string
          - type: 'null'
          title: License Server Allowlist Host
        license_server_allowlist_ip:
          anyOf:
          - type: string
          - type: 'null'
          title: License Server Allowlist Ip
        reset_required:
          type: boolean
          title: Reset Required
          default: false
        cleanup_in_progress:
          type: boolean
          title: Cleanup In Progress
          default: false
        company_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Company Id
        package_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Package Id
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
        team_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Team Size
        locale:
          anyOf:
          - type: string
          - type: 'null'
          title: Locale
        database:
          anyOf:
          - $ref: '#/components/schemas/SelfServiceWorkspaceDatabaseDraftResponse'
          - type: 'null'
        last_reset_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Reset Reason
        cleanup_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Cleanup Error
        stripe_subscription_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Stripe Subscription Id
        stripe_subscription_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Stripe Subscription Status
        stripe_current_period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Stripe Current Period End
        stripe_cancel_at_period_end:
          type: boolean
          title: Stripe Cancel At Period End
          default: false
        active_stripe_price_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Active Stripe Price Id
      type: object
      required:
      - status
      - resume_step
      title: SelfServiceWorkspaceStateResponse
    SelfServiceWorkspaceDatabaseDraftResponse:
      properties:
        type:
          anyOf:
          - type: string
          - type: 'null'
          title: Type
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        host:
          anyOf:
          - type: string
          - type: 'null'
          title: Host
        port:
          anyOf:
          - type: integer
          - type: 'null'
          title: Port
        database:
          anyOf:
          - type: string
          - type: 'null'
          title: Database
        username:
          anyOf:
          - type: string
          - type: 'null'
          title: Username
        ssl_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Ssl Mode
      type: object
      title: SelfServiceWorkspaceDatabaseDraftResponse
    RedirectTokenConsumeResponse:
      properties:
        redirect_url:
          type: string
          title: Redirect Url
        license_key:
          type: string
          title: License Key
        license_id:
          type: string
          format: uuid
          title: License Id
        customer_id:
          type: string
          title: Customer Id
        deployment_id:
          type: string
          format: uuid
          title: Deployment Id
        features:
          type: object
          title: Features
        limits:
          type: object
          title: Limits
      type: object
      required:
      - redirect_url
      - license_key
      - license_id
      - customer_id
      - deployment_id
      title: RedirectTokenConsumeResponse
    ActivationRequest:
      properties:
        license_key:
          type: string
          title: License Key
          description: License key
        machine_id:
          type: string
          title: Machine Id
          description: Unique machine identifier
        machine_hostname:
          anyOf:
          - type: string
          - type: 'null'
          title: Machine Hostname
          description: Machine hostname
        machine_ip:
          anyOf:
          - type: string
          - type: 'null'
          title: Machine Ip
          description: Machine IP address
        system_info:
          anyOf:
          - type: object
          - type: 'null'
          title: System Info
          description: System information (OS, RAM, CPU)
          example:
            cpu_cores: 8
            os: Ubuntu 22.04
            ram_gb: 32
        installation_path:
          anyOf:
          - type: string
          - type: 'null'
          title: Installation Path
          description: Installation directory path
      type: object
      required:
      - license_key
      - machine_id
      title: ActivationRequest
      description: Request model for license activation
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DeploymentStatusEnum:
      type: string
      enum:
      - active
      - terminated
      - failed
      title: DeploymentStatusEnum
      description: Deployment status enumeration
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SelfServiceWorkspaceResetResponse:
      properties:
        success:
          type: boolean
          title: Success
          default: true
        message:
          type: string
          title: Message
        workspace:
          anyOf:
          - $ref: '#/components/schemas/SelfServiceWorkspaceStateResponse'
          - type: 'null'
        redirect_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Redirect Url
        skipped:
          type: boolean
          title: Skipped
          default: false
      type: object
      required:
      - message
      title: SelfServiceWorkspaceResetResponse