secure-flows-com Users API

openapi: 3.2.0
info:
  title: secureFlows Management Users API
  version: 1.8.0
  description: 'REST API for **workspace owners/admins** and **end-user flows** (login, invites, anonymous, self-service).


    Base path: **`/api/v1`**.


    ### Workspace access policies

    Each workspace has two independent toggles (see **`Workspace`**, **`WorkspaceCreateRequest`**, **`WorkspaceUpdateRequest`**):


    | Field | Default | Controls |

    |-------|---------|----------|

    | **`acceptAnonimous`** | `true` | Whether anonymous Firebase users may join via **`POST /users/anonymous`** or session create without a prior invite |

    | **`enableSelfService`** | `true` | Whether end users may use the self-service dashboard (**`GET /users/memberships`**, **`POST /users/login`** as `USER`/`ANONIMOUS`, **`GET /sessions/my`**, **`POST /sessions/revoke/{sessionId}`**) |


    When **`enableSelfService`** is `false`, those self-service routes return **403** for end-user roles; **`ADMIN`** and **`OWNER`** console login via **`POST /users/login`** is unchanged.


    ### Error responses

    Failures return JSON **`{"status": , "error": ""}`** unless noted otherwise.

    Billing plan limit failures use **HTTP 429** with stable **`code`** values

    **`BILLING_SESSION_LIMIT`** or **`BILLING_PAYLOAD_LIMIT`** (see session create / payload write paths).


    ### Firebase email (console, audit, integrated app UI)

    Verified Firebase ID tokens may include an **`email`** claim. The server **best-effort** persists it on

    the workspace user row when missing — on **`POST /users/login`**, **`GET /users`** (current page),

    **`GET /users/{id}`**, session create/get-or-create/renew, and **`GET /auth/callback`** (create/renew).

    This does not change authentication; it helps **`GET /users`**, **`GET /audit/events`**, and

    **`GET /audit/api-access`** return emails instead of Firebase UIDs where possible. Clients do not

    send email in request bodies.


    **Integrated apps:** after sign-in, call **`GET /sessions/identity`** with the session token to display

    the signed-in user''s email in the app UI (e.g. next to **Sign out**) and to get a stable `userId` for

    your own backend to correlate external events against. Response: `{ "userId": 42, "email": "…" }`,

    either field may be `null`. Session **payload** remains on **`GET /sessions`** only.


    ### Paging and sorting

    Paged list endpoints return **`{ items, page, pageSize, totalItems, totalPages }`**. Page size is

    clamped to **`[1, 200]`**; query **`pageSize=0`** means default **20** (except where noted below).


    | Endpoint | Search (`q`) | Sort (`sort` / `dir`) |

    |----------|----------------|------------------------|

    | `GET /users` | email, name, UID, role, status, id | `email`, `name`, `role`, `status`, `id` |

    | `GET /audit/events` | — | fixed newest-first |

    | `GET /audit/api-access` | — | fixed newest-first |

    | `GET /sessions/admin` | id, user, app | session columns (see path) |

    | `GET /sessions/my` | id, app, status | session columns (see path) |

    | `GET /sessions/admin/analytics/concurrent-sessions` | — | fixed date ascending |


    Admin session list page size is fixed by server config (`sessions.admin.page-size`, default **10**).

    Export uses `sessions.export.page-size` (default **100**).


    ### Tokens

    | Kind | Use |

    |------|-----|

    | **Firebase ID token** | `POST /workspaces` (create), `GET /users/memberships`, `POST /users/login`, `POST /users/from-invite`, `POST /users/anonymous`, `POST /sessions`, `POST /sessions/get-or-create`, `POST /sessions/renew/{sessionToken}` — header `Authorization: Bearer ` |

    | **Internal USER JWT** | All other routes in this document — same header; issued by backend (`tokenType=USER`) |


    ### Related specs

    - **Hosted login & application registration**: see **`/docs/openapi/integration-auth.yaml`**

    - **AI session API only**: **`/docs/openapi/session/secure-flows-session-api.yaml`**


    Tags marked **`human-only`** describe console-style usage (not the session-only AI surface).'
tags:
- name: Users
  description: Workspace user directory (ADMIN/OWNER)
paths:
  /api/v1/users:
    get:
      summary: List users in the caller's workspace (paged)
      description: 'Paged user list for the workspace in the **internal USER JWT** (`workspace` claim). Requires

        workspace **ADMIN** or **OWNER**.


        Query **`q`** searches email, user name, Firebase UID, role, status, and numeric id.

        **`sort`**: `email` (default), `name`, `role`, `status`, `id`. **`dir`**: `asc` (default) or `desc`.

        **`pageSize`**: `0` means default **20** (clamped to `[1, 200]`).


        For FIREBASE users with a missing `email` on the current page, the server **best-effort** loads

        email from Firebase Admin, persists it, and returns it in the response.'
      tags:
      - Users
      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: 0
          maximum: 200
          default: 0
        description: 0 = default 20; max 200
      - name: q
        in: query
        required: false
        schema:
          type: string
        description: Search email, name, provider UID, role, status, or id
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - email
          - name
          - role
          - status
          - id
          default: email
      - name: dir
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      responses:
        '200':
          description: Paged users list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPageResponse'
              example:
                items:
                - id: 1
                  workspaceId: 1
                  role: OWNER
                  providerUid: p2G3qPWP8sZYST3cCORPUZCbXN72
                  userName: null
                  email: owner@example.com
                  status: active
                  authProvider: FIREBASE
                page: 0
                pageSize: 20
                totalItems: 1
                totalPages: 1
        '401':
          description: Missing or invalid USER token
        '403':
          description: Requires workspace ADMIN or OWNER
      operationId: getApiV1Users
      x-operation-id-source: derived
components:
  schemas:
    UserDto:
      type: object
      properties:
        id:
          type: integer
          example: 1
        workspaceId:
          type: integer
          example: 1
        role:
          type: string
          example: OWNER
        providerUid:
          type: string
          example: p2G3qPWP8sZYST3cCORPUZCbXN72
        userName:
          type: string
          nullable: true
          example: bob
        email:
          type: string
          nullable: true
          description: 'Best-effort from Firebase (login, session flows, or `GET /users` / `GET /users/{id}` Admin lookup).

            Display only; not used for authentication.

            '
          example: user@example.com
        status:
          type: string
          example: active
        authProvider:
          type: string
          example: FIREBASE
    UserPageResponse:
      type: object
      required:
      - items
      - page
      - pageSize
      - totalItems
      - totalPages
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/UserDto'
        page:
          type: integer
          description: Zero-based page index
        pageSize:
          type: integer
        totalItems:
          type: integer
          format: int64
        totalPages:
          type: integer
  securitySchemes:
    firebaseBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: '**Firebase ID token** from the client SDK (`Authorization: Bearer <token>`).

        When the token includes `email`, session endpoints best-effort persist it on the workspace end-user row

        (audit display only; no extra request fields).

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

        '
    sessionBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Internal session JWT from `POST /api/v1/sessions` or `POST /api/v1/sessions/get-or-create`

        (`tokenType=SESSION`; subject = session id).

        '