Cayra Stripe API

openapi: 3.2.0
info:
  title: Cayra License Server Stripe 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: Stripe
paths:
  /api/v1/me/subscription:
    get:
      tags:
      - Stripe
      summary: Get Subscription
      description: 'Return the current subscription state.


        Accepts license_key as query param (used by react_client via BFF).

        Returns has_subscription=false if no Stripe subscription found.


        Backward compatibility: if stripe_customer_id is set but stripe_subscription_id

        is missing (legacy user subscribed before new fields were added), perform a

        one-time lazy sync from the Stripe API and persist the result.'
      operationId: get_subscription_api_v1_me_subscription_get
      parameters:
      - name: license_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/checkout:
    post:
      tags:
      - Stripe
      summary: Create Checkout
      description: 'Create a Stripe Checkout Session.

        Accepts license_key query param (BFF) or Clerk JWT Bearer token.'
      operationId: create_checkout_api_v1_me_checkout_post
      parameters:
      - name: license_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/billing-portal:
    post:
      tags:
      - Stripe
      summary: Create Billing Portal
      description: 'Create a Stripe Customer Portal session.

        Accepts license_key query param (BFF proxy) or Clerk JWT Bearer token.'
      operationId: create_billing_portal_api_v1_me_billing_portal_post
      parameters:
      - name: license_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPortalResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/upgrade-preview:
    get:
      tags:
      - Stripe
      summary: Upgrade Preview
      description: 'Preview the proration cost of switching to a new plan.

        For upgrades: returns the amount charged immediately (prorated).

        For downgrades: amount_due_now is 0, change takes effect at period end.'
      operationId: upgrade_preview_api_v1_me_upgrade_preview_get
      parameters:
      - name: package_id
        in: query
        required: true
        schema:
          type: string
          title: Package Id
      - name: billing_cycle
        in: query
        required: false
        schema:
          type: string
          default: monthly
          title: Billing Cycle
      - name: license_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradePreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/setup-intent:
    post:
      tags:
      - Stripe
      summary: Create Setup Intent
      description: 'Create a Stripe SetupIntent for the current customer so the frontend can

        collect a payment method via Stripe Elements without making a charge.


        Used when a trial user (no card on file) wants to upgrade to a paid plan:

        1. Frontend calls this endpoint → receives client_secret

        2. Stripe Elements confirms the setup (card saved to customer, no charge)

        3. Frontend calls /upgrade-checkout as normal — card is now on file

        4. Backend: trial_end=''now'' fires, user is charged immediately'
      operationId: create_setup_intent_api_v1_me_setup_intent_post
      parameters:
      - name: license_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupIntentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/credit-packs:
    get:
      tags:
      - Stripe
      summary: List Credit Packs
      description: 'Return available credit add-on packs from the deployment_packages table

        (rows where is_credit_pack = true).'
      operationId: list_credit_packs_api_v1_me_credit_packs_get
      parameters:
      - name: license_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditPackListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/me/credit-pack-checkout:
    post:
      tags:
      - Stripe
      summary: Create Credit Pack Checkout
      description: 'Create a Stripe Checkout Session (mode=payment) for a credit add-on pack.

        pack_id is the DeploymentPackage UUID (from /me/credit-packs).

        Returns the checkout URL to redirect the user to.'
      operationId: create_credit_pack_checkout_api_v1_me_credit_pack_checkout_post
      parameters:
      - name: license_key
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: License Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditPackCheckoutRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreditPackInfo:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        credits:
          type: integer
          title: Credits
        price_usd:
          type: number
          title: Price Usd
        price_id:
          type: string
          title: Price Id
      type: object
      required:
      - id
      - name
      - credits
      - price_usd
      - price_id
      title: CreditPackInfo
    SubscriptionWarning:
      properties:
        type:
          type: string
          title: Type
        message:
          type: string
          title: Message
        severity:
          type: string
          title: Severity
      type: object
      required:
      - type
      - message
      - severity
      title: SubscriptionWarning
    UpgradePreviewResponse:
      properties:
        is_upgrade:
          type: boolean
          title: Is Upgrade
        amount_due_now:
          type: number
          title: Amount Due Now
        next_invoice_amount:
          type: number
          title: Next Invoice Amount
        next_billing_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Billing Date
        new_package_name:
          type: string
          title: New Package Name
        new_monthly_credits:
          type: integer
          title: New Monthly Credits
        currency:
          type: string
          title: Currency
          default: usd
        requires_card:
          type: boolean
          title: Requires Card
          default: false
      type: object
      required:
      - is_upgrade
      - amount_due_now
      - next_invoice_amount
      - next_billing_date
      - new_package_name
      - new_monthly_credits
      title: UpgradePreviewResponse
    PackageInfo:
      properties:
        id:
          type: string
          title: Id
        code:
          type: string
          title: Code
        name:
          type: string
          title: Name
        credits_total:
          type: integer
          title: Credits Total
        price_usd_monthly:
          anyOf:
          - type: number
          - type: 'null'
          title: Price Usd Monthly
        price_usd_yearly:
          anyOf:
          - type: number
          - type: 'null'
          title: Price Usd Yearly
      type: object
      required:
      - id
      - code
      - name
      - credits_total
      title: PackageInfo
    SubscriptionResponse:
      properties:
        has_subscription:
          type: boolean
          title: Has Subscription
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        billing_cycle:
          anyOf:
          - type: string
          - type: 'null'
          title: Billing Cycle
        current_period_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Current Period End
        cancel_at_period_end:
          type: boolean
          title: Cancel At Period End
          default: false
        package:
          anyOf:
          - $ref: '#/components/schemas/PackageInfo'
          - type: 'null'
        current_balance:
          anyOf:
          - type: number
          - type: 'null'
          title: Current Balance
        warnings:
          items:
            $ref: '#/components/schemas/SubscriptionWarning'
          type: array
          title: Warnings
          default: []
        package_features:
          anyOf:
          - type: object
          - type: 'null'
          title: Package Features
        pending_downgrade_package_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Pending Downgrade Package Name
      type: object
      required:
      - has_subscription
      title: SubscriptionResponse
    CheckoutRequest:
      properties:
        package_id:
          type: string
          format: uuid
          title: Package Id
        billing_cycle:
          type: string
          title: Billing Cycle
          default: monthly
      type: object
      required:
      - package_id
      title: CheckoutRequest
    SetupIntentResponse:
      properties:
        client_secret:
          type: string
          title: Client Secret
      type: object
      required:
      - client_secret
      title: SetupIntentResponse
    BillingPortalResponse:
      properties:
        portal_url:
          type: string
          title: Portal Url
      type: object
      required:
      - portal_url
      title: BillingPortalResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CheckoutResponse:
      properties:
        checkout_url:
          type: string
          title: Checkout Url
      type: object
      required:
      - checkout_url
      title: CheckoutResponse
    CreditPackCheckoutRequest:
      properties:
        pack_id:
          type: string
          title: Pack Id
      type: object
      required:
      - pack_id
      title: CreditPackCheckoutRequest
    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
    CreditPackListResponse:
      properties:
        packs:
          items:
            $ref: '#/components/schemas/CreditPackInfo'
          type: array
          title: Packs
      type: object
      required:
      - packs
      title: CreditPackListResponse