> ## Documentation Index
> Fetch the complete documentation index at: https://trueforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List users

> List users in the tenant that sessions can be shared with. Searches email and display name, or looks up specific users with `ids`.



## OpenAPI

````yaml /openapi.json get /api/v1/users
openapi: 3.1.0
info:
  description: >-
    HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are
    served at `/api/v1/docs` (OpenAPI JSON at `/api/v1/openapi.json`).


    **Authentication:** Standalone auth accepts requests without credentials —
    middleware stamps a local default user. When OIDC or TrueFoundry auth is
    configured, protected routes require a valid cookie or `Authorization:
    Bearer` token. There is no built-in API-key scheme; pass custom headers only
    if your reverse proxy or IdP layer requires them.


    Covers DB-backed sessions, the agent registry, settings catalogs, and
    model/MCP/skill/sandbox providers.
  title: TrueForge API
  version: 0.0.0
servers: []
security:
  - BearerAuth: []
tags:
  - name: Internal
  - name: Auth
  - name: Users
  - name: Capabilities
  - name: Models
  - name: MCP Servers
  - name: Skills
  - name: Sandboxes
  - name: Web Search Providers
  - name: Memory Providers
  - name: Configuration
  - name: Agents
  - name: Schedules
  - name: Agent Sessions
paths:
  /api/v1/users:
    get:
      tags:
        - Users
      summary: List users
      description: >-
        List users in the tenant that sessions can be shared with. Searches
        email and display name, or looks up specific users with `ids`.
      parameters:
        - description: Case-insensitive substring match on email or display name.
          in: query
          name: query
          required: false
          schema:
            description: Case-insensitive substring match on email or display name.
            maxLength: 200
            minLength: 1
            type: string
        - description: Page size. Defaults to 25, max 100.
          in: query
          name: limit
          required: false
          schema:
            default: 25
            description: Page size. Defaults to 25, max 100.
            maximum: 100
            minimum: 1
            type: integer
        - description: Opaque token from a previous response `next_page_token`.
          in: query
          name: page_token
          required: false
          schema:
            description: Opaque token from a previous response `next_page_token`.
            type: string
        - description: >-
            Return only these users (comma-separated ids, up to 100). Users that
            are unknown or inactive are omitted. Cannot be combined with `query`
            or `page_token`.
          in: query
          name: ids
          required: false
          schema:
            description: >-
              Return only these users (comma-separated ids, up to 100). Users
              that are unknown or inactive are omitted. Cannot be combined with
              `query` or `page_token`.
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUsersResponse'
          description: Paginated users.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
          description: Invalid query parameters or page token.
components:
  schemas:
    ListUsersResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/User'
          type: array
        pagination:
          $ref: '#/components/schemas/TokenPagination'
      required:
        - data
        - pagination
      type: object
    RequestErrorResponse:
      properties:
        error:
          properties:
            code:
              description: Optional machine-readable error code; null when not applicable.
              type:
                - string
                - 'null'
            message:
              description: Human-readable explanation of the failure.
              type: string
            param:
              description: >-
                Optional request field that caused the error; null when not
                field-specific.
              type:
                - string
                - 'null'
            type:
              description: Optional error category (e.g. validation vs conflict).
              type: string
          required:
            - message
          type: object
      required:
        - error
      type: object
    User:
      properties:
        display_name:
          description: Human-readable name for the user.
          type: string
        email:
          description: Email of the user.
          type: string
        id:
          description: User id, unique within the tenant.
          type: string
      required:
        - id
        - display_name
        - email
      type: object
    TokenPagination:
      properties:
        limit:
          description: Page size used for this response.
          exclusiveMinimum: 0
          type: integer
        next_page_token:
          description: >-
            Opaque token for the next page. Omit or absent when there is no next
            page.
          type: string
        previous_page_token:
          description: >-
            Opaque token for the previous page. Omit or absent when there is no
            previous page.
          type: string
      required:
        - limit
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: >-
        Caller credential (`Authorization: Bearer <token>`). Required on
        protected routes when auth is enabled. Browser sessions may use the
        HttpOnly `id_token` or `accessToken` cookie instead.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.