Cayra Mobile Invite API

openapi: 3.2.0
info:
  title: Cayra License Server Mobile Invite 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: Mobile Invite
paths:
  /api/v1/auth/invite:
    post:
      tags:
      - Mobile Invite
      summary: Create invite token (admin)
      description: 'Admin endpoint: create a deferred deep-link invite token for a specific user.


        Stores {url, phone, otp} under a short-lived token.

        Mobile app resolves it via GET /api/v1/auth/invite/{token}.


        Requires X-Admin-API-Key header.'
      operationId: create_invite_api_v1_auth_invite_post
      parameters:
      - name: x-admin-api-key
        in: header
        required: false
        schema:
          type: string
          title: X-Admin-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/invite/qr-allocate:
    post:
      tags:
      - Mobile Invite
      summary: Auto-allocate test user invite (public QR endpoint)
      description: 'Public endpoint called by the fixed QR landing page.


        Automatically picks the next available test user from the pool

        (+900000000002 … +900000000201), creates an invite token, and returns

        the deep-link URL.


        Rate limited to 5 requests per IP per minute to prevent pool exhaustion.'
      operationId: qr_allocate_invite_api_v1_auth_invite_qr_allocate_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteCreateResponse'
  /api/v1/auth/invite/{token}:
    get:
      tags:
      - Mobile Invite
      summary: Resolve and consume invite token (public)
      description: 'Public endpoint called by the mobile app after catching the deep link.


        Returns {url, phone, otp} and immediately deletes the token (single-use).

        Returns 404 if the token does not exist or has expired.'
      operationId: resolve_invite_api_v1_auth_invite__token__get
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InviteResolveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/auth/invite/mark-used:
    patch:
      tags:
      - Mobile Invite
      summary: Mark pool user as logged_in (public)
      description: 'Public endpoint called by the mobile app after a successful OTP login.


        Marks the phone number as logged_in in the test pool so it won''t be

        re-assigned to another QR scan.'
      operationId: mark_invite_used_api_v1_auth_invite_mark_used_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkUsedRequest'
        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:
    InviteCreateRequest:
      properties:
        url:
          type: string
          title: Url
          description: Target Cayra instance URL, e.g. https://company.cayra.io
        phone:
          type: string
          title: Phone
          description: User phone number in E.164 format
        otp:
          type: string
          maxLength: 6
          minLength: 6
          title: Otp
          description: 6-digit OTP code
      type: object
      required:
      - url
      - phone
      - otp
      title: InviteCreateRequest
    MarkUsedRequest:
      properties:
        phone:
          type: string
          title: Phone
          description: Phone number to mark as logged_in
      type: object
      required:
      - phone
      title: MarkUsedRequest
    InviteCreateResponse:
      properties:
        token:
          type: string
          title: Token
        invite_url:
          type: string
          title: Invite Url
      type: object
      required:
      - token
      - invite_url
      title: InviteCreateResponse
    InviteResolveResponse:
      properties:
        url:
          type: string
          title: Url
        phone:
          type: string
          title: Phone
        otp:
          type: string
          title: Otp
      type: object
      required:
      - url
      - phone
      - otp
      title: InviteResolveResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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