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

# List users

> Lists the workspace's people: its members, and guests who are visible to them. Deactivated and removed people stay listed with `is_active: false`. Bots are never listed. `email` is present only with the `users:read.email` scope, and only when the person lets colleagues see it. Needs `users:read`. Limited to 20 requests a minute per installation.



## OpenAPI

````yaml /openapi/staging.json get /v1/users
openapi: 3.0.0
info:
  contact:
    email: support@workchats.com
    name: Workchats API Support
  description: >
    Post messages into Workchats as an installed App's bot user, and read

    the people and conversations it can reach.


    Authenticate with the bot token from the OAuth install, in the

    Authorization header as `Bearer wc_bot_…`. Every error response has

    the shape `{"ok": false, "error": {"code", "message"}, "request_id"}`.


    Lists are cursor-paginated: pass `limit` (default 200, at most 1000)

    and the previous page's `next_cursor` as `cursor`. `next_cursor` is

    null on the last page.


    ## Callbacks


    Workchats POSTs events to the App's registered callback URL, over

    HTTPS only. Answer with any 2xx within 3 seconds. Anything else,

    including a redirect, which is never followed, is retried after 1, 5

    and 30 minutes with the same event `id`, so ignore an `id` you have

    already handled. `X-Workchats-Attempt` counts the attempts from 1.


    Every event has the shape `{"id", "type", "workspace_id",

    "created_at", "data"}`:


    - `app.uninstalled`: `data` is `{"removed_by": {"id": "usr_…"} | null,
      "reason": "admin" | "app_disabled"}`. A company admin uninstalled
      the App, or Workchats disabled it (`removed_by` is null). The token
      has already stopped working. Revoking the token yourself through
      `POST /oauth/revoke` sends nothing.
    - `directory.changed`: `data` is `{"kind", "id"}`. Re-read the user
      with `GET /v1/users/{id}` or the conversation with
      `GET /v1/conversations/{id}`. Kinds: `user.created`,
      `user.updated` (name, email or title), `user.deactivated`
      (deactivated or removed), `conversation.created` (the bot was
      added), `conversation.renamed`, `conversation.archived` (groups),
      `conversation.deleted`, `app.removed_from_conversation`. User kinds
      need `users:read`; conversation kinds name only conversations the
      bot is, or was just, in. Ignore kinds you don't know.

    **Verifying a callback.** `X-Workchats-Signature` is `v1=` and the

    lower-case hex HMAC-SHA256 of `<X-Workchats-Timestamp>.<raw body>`,

    keyed with the App's signing secret. Compare in constant time, and

    refuse a timestamp more than 5 minutes old. For 24 hours after the

    secret is rotated the header carries two signatures,

    `v1=<new>,v1=<old>`: accept the request if any one matches.


    Worked example:


    - Signing secret: `whsec_docs_example`

    - X-Workchats-Timestamp: 1790593600

    - Body:
    `{"id":"evt_5f0c7a52-6d1e-4c1b-9a8e-2f4b7c3d1e90","type":"directory.changed","workspace_id":"cmp_0b7e4c1a-2d3f-4a5b-8c6d-7e8f9a0b1c2d","created_at":"2026-09-28T11:06:40Z","data":{"kind":"user.deactivated","id":"usr_9a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"}}`

    - X-Workchats-Signature:
    v1=42ec825e4ad44370ea02385d30a001c349640cff974ed895361b3c7a080e5339
  title: Workchats Public API
  version: '1.0'
servers:
  - url: https://public-api.staging.workchats.com
    variables: {}
security:
  - bearerAuth: []
tags:
  - description: Token checks
    name: Auth
  - description: Groups and channels the bot is a member of, and their messages
    name: Conversations
  - description: Files attached to messages the bot can read
    name: Files
  - description: Send, edit and delete the bot's messages
    name: Messages
  - description: Code exchange and token revocation
    name: OAuth
  - description: The workspace's people
    name: Users
paths:
  /v1/users:
    get:
      tags:
        - Users
      summary: List users
      description: >-
        Lists the workspace's people: its members, and guests who are visible to
        them. Deactivated and removed people stay listed with `is_active:
        false`. Bots are never listed. `email` is present only with the
        `users:read.email` scope, and only when the person lets colleagues see
        it. Needs `users:read`. Limited to 20 requests a minute per
        installation.
      operationId: WorkchatsApiServerWeb.PublicApi.UserController.index
      parameters:
        - description: Page size, 200 by default. Values above 1000 are clamped.
          in: query
          name: limit
          required: false
          schema:
            default: 200
            minimum: 1
            type: integer
        - description: The previous page's `next_cursor`. Omit it for the first page.
          in: query
          name: cursor
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiUsersResponse'
          description: A page of users
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          description: >-
            `invalid_cursor`, `invalid_request` (a bad `limit`, or a body that
            could not be parsed) or `token_in_query`
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          description: '`not_authed`, `invalid_auth` or `token_revoked`'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          description: '`missing_scope`: the token lacks `users:read`'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          description: '`not_acceptable`: the Accept header does not allow application/json'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          description: '`rate_limited`: retry after the Retry-After header''s seconds'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          description: '`internal_error`: something went wrong on our side'
      callbacks: {}
      security:
        - bearerAuth: []
components:
  schemas:
    PublicApiUsersResponse:
      description: A page of users, oldest first.
      properties:
        next_cursor:
          description: Pass as `cursor` for the next page; null on the last page
          nullable: true
          type: string
        ok:
          enum:
            - true
          type: boolean
        users:
          items:
            $ref: '#/components/schemas/PublicApiUser'
          type: array
      required:
        - ok
        - users
        - next_cursor
      title: PublicApiUsersResponse
      type: object
    PublicApiError:
      description: Every non-2xx response from the public API.
      example:
        error:
          code: token_revoked
          message: The token has been revoked.
        ok: false
        request_id: F7p0mJcXk3tq2x0AAAAB
      properties:
        error:
          properties:
            code:
              description: >-
                Stable, machine-readable error code. Each code always comes with
                the same HTTP status, except `client_error` and `server_error`,
                which carry the response's own 4xx or 5xx status. New codes may
                be added; treat an unknown one as a generic failure.
              type: string
              x-extensible-enum:
                - cannot_dm_user
                - client_error
                - conversation_archived
                - conversation_not_found
                - file_not_found
                - idempotency_key_reused
                - internal_error
                - invalid_auth
                - invalid_blocks
                - invalid_client
                - invalid_cursor
                - invalid_grant
                - invalid_request
                - message_not_found
                - missing_idempotency_key
                - missing_scope
                - not_acceptable
                - not_allowed_in_conversation
                - not_authed
                - not_found
                - not_in_conversation
                - payload_too_large
                - rate_limited
                - server_error
                - token_in_query
                - token_revoked
                - unsupported_grant_type
                - unsupported_media_type
                - user_deactivated
                - user_not_found
            message:
              description: Human-readable explanation
              type: string
          required:
            - code
            - message
          type: object
        ok:
          enum:
            - false
          type: boolean
        request_id:
          description: Also sent as the X-Request-Id header. Quote it to support.
          type: string
      required:
        - ok
        - error
        - request_id
      title: PublicApiError
      type: object
    PublicApiUser:
      description: >-
        A person in the workspace. `email` is present only with the
        `users:read.email` scope, and only when the person lets colleagues see
        it; a removed person never has one. Phone numbers are never included.
      example:
        avatar_url: https://cdn.workchats.com/a/9a1d2c3e.png
        display_name: Connor
        email: connor@corpwise.ae
        id: usr_9a1d2c3e-4b5f-4a6b-8c7d-9e0f1a2b3c4d
        is_active: true
        is_admin: false
        is_bot: false
        is_external: false
        name: Connor Berwick
        timezone: Asia/Dubai
        title: Sales
      properties:
        avatar_url:
          format: uri
          nullable: true
          type: string
        display_name:
          description: First name
          nullable: true
          type: string
        email:
          description: Absent when withheld
          format: email
          type: string
        id:
          description: User id, `usr_` prefixed
          type: string
        is_active:
          description: False for deactivated and removed people, who stay listed
          type: boolean
        is_admin:
          description: A company admin
          type: boolean
        is_bot:
          description: Bots are never listed
          enum:
            - false
          type: boolean
        is_external:
          description: A guest from outside the company
          type: boolean
        name:
          description: Full name
          type: string
        timezone:
          description: IANA timezone
          nullable: true
          type: string
        title:
          description: Job title
          nullable: true
          type: string
      required:
        - id
        - name
        - display_name
        - avatar_url
        - title
        - timezone
        - is_active
        - is_bot
        - is_admin
        - is_external
      title: PublicApiUser
      type: object
  securitySchemes:
    bearerAuth:
      description: Bot token (`wc_bot_live_…` or `wc_bot_test_…`) from the OAuth install
      scheme: bearer
      type: http

````