secure-flows-com AI Optional API

openapi: 3.2.0
info:
  title: Secure Flows Com AI Optional API
  version: '1.0'
  description: 'Operations tagged ai-optional across 2 of this provider''s published API definitions: secure-flows-session-api.yaml, secure-flows-user-api.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: ai-optional
paths:
  /api/v1/sessions/renew/{sessionToken}:
    post:
      summary: Renew session JWT (replace expired token)
      description: 'Verifies **Firebase** ID token. Parses **`sessionToken`** path segment as an internal SESSION JWT **without

        enforcing JWT expiry** (signature and `tokenType=SESSION` are still validated). Loads the

        session by id from the token subject; the Firebase UID must match the session owner.

        Increments **`tokenRevision`** on the server so **previous session JWTs** (same session id,

        older revision) are no longer accepted for `GET/POST/DELETE /sessions/...`.

        Returns a **new `sessionToken`** (with the new `tokenRevision` claim) and the current decrypted

        **payload**; extends server-side session expiry by **1 hour**.


        If the Firebase token includes **`email`**, the server best-effort backfills it on the session owner

        when the user row has no email yet (audit display only).


        Use the path form `POST /api/v1/sessions/renew/{sessionToken}` — **URL-encode** the JWT (e.g. `encodeURIComponent` in JS).'
      tags:
      - ai-optional
      security:
      - firebaseBearerAuth: []
      parameters:
      - name: sessionToken
        in: path
        required: true
        schema:
          type: string
        description: Previous SESSION JWT (may be expired); URL-encoded in the path
      responses:
        '200':
          description: New session token and payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionRenewResponse'
        '400':
          description: Empty session token path segment (if applicable).
        '401':
          description: Missing Authorization, invalid Firebase token, or invalid session token (signature / shape).
        '403':
          description: 'Firebase user does not own this session, or workspace is in `grace_lock`

            (`code: BILLING_GRACE_LOCK`).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                notOwner:
                  value:
                    status: 403
                    error: Firebase user does not own this session
                graceLock:
                  value:
                    status: 403
                    code: BILLING_GRACE_LOCK
                    error: Workspace is locked after paid period ended without Free downgrade; end-user session access is blocked until you Downgrade to Free (reduce usage first if over Free limits)
        '404':
          description: Session id not found.
        '410':
          description: Session revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: 410
                error: Session revoked
      operationId: postApiV1SessionsRenewBySessionToken
      x-operation-id-source: derived
  /api/v1/sessions/my:
    get:
      tags:
      - ai-optional
      summary: List my sessions (paged, sortable, filterable)
      description: 'Returns a page of sessions for the current user within the current workspace.

        Self-service dashboard endpoint — requires workspace **`enableSelfService: true`**.

        Payload is included only for rows whose computed status is active.

        Sort keys match the admin workspace session list; `pageSize` is clamped to 1–200 (default 20).'
      security:
      - userBearerAuth: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: pageSize
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
        description: Page size (server clamps to 1–200; 0 or invalid uses default 20).
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search by session id, app id, or user identifier (own uid)
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - active
          - expired
          - revoked
          default: all
        description: Computed session lifecycle filter (`all` or same values as admin session list).
      - name: app_id
        in: query
        required: false
        schema:
          type: string
          default: all
        description: Filter by client app id, or `all`.
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - id
          - user
          - app
          - created
          - expires
          - status
          - lastActivity
          - updated
          default: created
      - name: dir
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: Paged sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionUserPageResponse'
        '401':
          description: Missing or invalid internal USER token.
        '403':
          description: Self-service is disabled for this workspace.
          content:
            application/json:
              example:
                error: Self-service is disabled for this workspace
      operationId: getApiV1SessionsMy
      x-operation-id-source: derived
  /api/v1/sessions/revoke/{sessionId}:
    post:
      tags:
      - ai-optional
      summary: Revoke a session owned by the current user
      description: 'Self-service dashboard endpoint. Revokes a session owned by the caller in the current workspace.

        The session ends and its stored data is destroyed permanently; this is not sign-out.

        Requires workspace **`enableSelfService: true`**.'
      security:
      - userBearerAuth: []
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Revoked
          content:
            application/json:
              schema:
                type: object
                required:
                - revoked
                - sessionId
                properties:
                  revoked:
                    type: boolean
                  sessionId:
                    type: integer
        '401':
          description: Missing or invalid internal USER token.
        '403':
          description: Self-service is disabled for this workspace.
          content:
            application/json:
              example:
                error: Self-service is disabled for this workspace
        '404':
          description: Session not found (or not owned by user).
      operationId: postApiV1SessionsRevokeBySessionId
      x-operation-id-source: derived
components:
  schemas:
    SessionPayloadObject:
      type: object
      additionalProperties: true
      description: Decrypted key/value payload object
      example:
        hello: world
        counter: 1
    SessionRenewResponse:
      type: object
      required:
      - sessionToken
      - payload
      properties:
        sessionToken:
          type: string
          description: New internal JWT session token (tokenType=SESSION)
        payload:
          $ref: '#/components/schemas/SessionPayloadObject'
    ApiError:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Stable machine-readable error code (billing limit errors only)
          enum:
          - BILLING_SESSION_LIMIT
          - BILLING_PAYLOAD_LIMIT
          - BILLING_GRACE_LOCK
    SessionUserView:
      type: object
      description: Session payload + metadata view for the current user dashboard.
      required:
      - id
      - workspaceId
      - providerUid
      - status
      - payload
      properties:
        id:
          type: integer
          format: int64
        workspaceId:
          type: integer
          format: int64
        providerUid:
          type: string
        userEmail:
          type: string
          nullable: true
          description: Email from the workspace user row when known
        appId:
          type: string
          nullable: true
          description: Client application id when the session is bound to an app
        status:
          type: string
          example: active
        securityLevel:
          type: string
          nullable: true
          description: Best-effort classification from backend (may be null)
        tokenRevision:
          type: integer
          nullable: true
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        lastActivityAt:
          type: string
          format: date-time
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
        endedAt:
          type: string
          format: date-time
          nullable: true
        revokedBy:
          type: string
          nullable: true
        revokedByDisplayName:
          type: string
          nullable: true
        currentDataSizeBytes:
          type: integer
          format: int64
          nullable: true
        maxDataSizeBytes:
          type: integer
          format: int64
          nullable: true
        payload:
          $ref: '#/components/schemas/SessionPayload'
    SessionRenewResponse_2:
      type: object
      required:
      - sessionToken
      - payload
      properties:
        sessionToken:
          type: string
          description: New internal JWT (`tokenType=SESSION`)
        payload:
          $ref: '#/components/schemas/SessionPayload'
    SessionUserPageResponse:
      type: object
      required:
      - items
      - page
      - pageSize
      - totalItems
      - totalPages
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SessionUserView'
        page:
          type: integer
        pageSize:
          type: integer
        totalItems:
          type: integer
          format: int64
        totalPages:
          type: integer
    SessionPayload:
      type: object
      description: Decrypted session payload wrapper (`properties` holds key/value data).
      properties:
        properties:
          type: object
          additionalProperties: true
          description: Decrypted key/value map
  securitySchemes:
    firebaseBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Firebase ID token (`POST /sessions`, `POST /sessions/get-or-create`, `POST /sessions/renew/{sessionToken}`).

        When the token includes `email`, the server best-effort stores it on the workspace end-user row.

        '
    sessionBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Session JWT from `POST /sessions` or `POST /sessions/renew/{sessionToken}` (`tokenType=SESSION`; subject = session id;

        `tokenRevision` claim must match the server; superseded after renew)

        '
    userBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: '**Internal USER JWT** issued by this API (`tokenType=USER`). Contains workspace and role claims.

        '
externalDocs:
  description: API documentation hub
  url: ../index.html
x-refined-from:
- secure-flows-session-api.yaml
- secure-flows-user-api.yaml