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

# List organization users

> Retrieve a paginated list of all organization members together with their access rights.

    ## Overview

    Returns every user in your organization along with their organization role, workspace-level
    roles, and any explicit product-level role overrides.

    ## Search Functionality

    Use the `q` parameter to filter users by name or email:
    - Case-insensitive partial match
    - Searches within both the user's display name and email address
    - Example: `q=jane` will match "Jane Doe" or "jane@example.com"

    ## Access granularity

    | Level | Field | Values |
    |---|---|---|
    | Organization | `org_role` | `admin`, `member`, `guest` |
    | Workspace | `workspaceAccess[].role` | `editor`, `viewer` |
    | Product (override) | `productAccess[].role` | `editor`, `viewer`, `no_access` |

    Product-level entries are only emitted when an explicit override exists for that user/product
    pair. Without an override the user inherits their workspace role. A role of `no_access` means
    the user is explicitly blocked from that product regardless of their workspace role.

    ## Notes

    - Users who don't have a paid license have an organization role of `guest`.
    - Depending on the type of login (SSO, username/password, etc.), the user's name may be set to the email address.



## OpenAPI

````yaml /openapi.json get /v1/public/organization/users
openapi: 3.1.0
info:
  title: Poelis Public API
  description: |2-

            Poelis Public API - REST endpoints for external clients and integrations.
            
            ## Authentication
            
            All endpoints require an API key in the `Authorization` header:
            ```
            Authorization: Bearer poelis_api_...
            ```
            
            Get your API key from the web application's API Keys section.
            
            ## Rate Limiting
            
            API requests are rate-limited per organization. Contact support for higher limits.
            
            ## Support
            
            For questions or issues, contact support@poelis.com
            
  version: 1.0.0
servers:
  - url: https://api.poelis.com
    description: Production
  - url: http://localhost:8000
    description: Local
security: []
paths:
  /v1/public/organization/users:
    get:
      tags:
        - Organization
      summary: List organization users
      description: >-
        Retrieve a paginated list of all organization members together with
        their access rights.

            ## Overview

            Returns every user in your organization along with their organization role, workspace-level
            roles, and any explicit product-level role overrides.

            ## Search Functionality

            Use the `q` parameter to filter users by name or email:
            - Case-insensitive partial match
            - Searches within both the user's display name and email address
            - Example: `q=jane` will match "Jane Doe" or "jane@example.com"

            ## Access granularity

            | Level | Field | Values |
            |---|---|---|
            | Organization | `org_role` | `admin`, `member`, `guest` |
            | Workspace | `workspaceAccess[].role` | `editor`, `viewer` |
            | Product (override) | `productAccess[].role` | `editor`, `viewer`, `no_access` |

            Product-level entries are only emitted when an explicit override exists for that user/product
            pair. Without an override the user inherits their workspace role. A role of `no_access` means
            the user is explicitly blocked from that product regardless of their workspace role.

            ## Notes

            - Users who don't have a paid license have an organization role of `guest`.
            - Depending on the type of login (SSO, username/password, etc.), the user's name may be set to the email address.
      operationId: list_users_access_v1_public_organization_users_get
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Paginated list of users with their full role details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicUsersAccessResponse'
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '401':
          description: Unauthorized - Invalid or missing API key
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
                message: Invalid or missing API key
        '403':
          description: Forbidden - Access denied
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: forbidden
                message: Access denied
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: not_found
                message: Not found
        '422':
          description: Validation error - Invalid request body or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: validation_error
                message: Invalid data format
                details:
                  errors:
                    - loc:
                        - body
                        - field_name
                      msg: field required
                      type: value_error.missing
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: rate_limit_exceeded
                message: Too many requests
      security:
        - API Key: []
components:
  parameters:
    Query:
      name: q
      in: query
      required: false
      description: Optional search query to filter results.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return per page. Must be between 1 and 200.
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 200
      example: 50
    Offset:
      name: offset
      in: query
      required: false
      description: >-
        Number of items to skip from the beginning of the result set. Used for
        pagination.
      schema:
        type: integer
        default: 0
        minimum: 0
      example: 0
  schemas:
    PublicUsersAccessResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PublicUserAccessEntry'
          type: array
          title: Items
          description: List of users with their access rights
        count:
          type: integer
          title: Count
          description: Total number of users matching the query
      type: object
      required:
        - items
        - count
      title: PublicUsersAccessResponse
      description: Response payload for listing users with access rights.
      example:
        count: 1
        items:
          - email: jane.doe@example.com
            id: auth0|550e8400-e29b-41d4-a716-446655440000
            name: Jane Doe
            org_role: admin
            productAccess:
              - product_id: 660e8400-e29b-41d4-a716-446655440000
                product_name: Jet Engine Specifications
                role: viewer
                workspace_id: 550e8400-e29b-41d4-a716-446655440000
            workspaceAccess:
              - role: editor
                workspace_id: 550e8400-e29b-41d4-a716-446655440000
                workspace_name: Aerospace Engineering
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Machine-readable error code (e.g. validation_error, item_not_found).
        message:
          type: string
          description: Human-readable error message.
        details:
          type: object
          description: >-
            Additional error context (optional). For validation errors, contains
            a list of field-level issues.
          nullable: true
      required:
        - error
        - message
    PublicUserAccessEntry:
      properties:
        id:
          type: string
          title: Id
          description: User ID (Auth0 subject)
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: User email address
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Display name
        org_role:
          type: string
          title: Org Role
          description: >-
            Organization-level role: 'admin', 'member', or 'guest'. Guest users
            have workspace access but no formal organization role.
        workspaceAccess:
          items:
            $ref: '#/components/schemas/PublicUserWorkspaceAccess'
          type: array
          title: Workspaceaccess
          description: Workspace-level roles for each workspace this user is a member of.
        productAccess:
          items:
            $ref: '#/components/schemas/PublicUserProductAccess'
          type: array
          title: Productaccess
          description: >-
            Explicit product-level role overrides. Only populated when the user
            has a product-level override; products without an override inherit
            the workspace role.
      type: object
      required:
        - id
        - org_role
      title: PublicUserAccessEntry
      description: A user with their full access rights across the organization.
      example:
        email: jane.doe@example.com
        id: auth0|550e8400-e29b-41d4-a716-446655440000
        name: Jane Doe
        org_role: admin
        productAccess:
          - product_id: 660e8400-e29b-41d4-a716-446655440000
            product_name: Jet Engine Specifications
            role: viewer
            workspace_id: 550e8400-e29b-41d4-a716-446655440000
        workspaceAccess:
          - role: editor
            workspace_id: 550e8400-e29b-41d4-a716-446655440000
            workspace_name: Aerospace Engineering
    PublicUserWorkspaceAccess:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
          description: Workspace ID
        workspace_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Workspace Name
          description: Workspace name
        role:
          type: string
          title: Role
          description: 'Role within the workspace: ''editor'' or ''viewer'''
      type: object
      required:
        - workspace_id
        - role
      title: PublicUserWorkspaceAccess
      description: A user's role within a specific workspace.
      example:
        role: editor
        workspace_id: 550e8400-e29b-41d4-a716-446655440000
        workspace_name: Aerospace Engineering
    PublicUserProductAccess:
      properties:
        product_id:
          type: string
          title: Product Id
          description: Product ID
        product_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Name
          description: Product name
        workspace_id:
          type: string
          title: Workspace Id
          description: Workspace the product belongs to
        role:
          type: string
          title: Role
          description: >-
            Product-level role override: 'editor', 'viewer', or 'no_access'.
            Overrides workspace role for this product.
      type: object
      required:
        - product_id
        - workspace_id
        - role
      title: PublicUserProductAccess
      description: A user's explicit product-level role override.
      example:
        product_id: 660e8400-e29b-41d4-a716-446655440000
        product_name: Jet Engine Specifications
        role: viewer
        workspace_id: 550e8400-e29b-41d4-a716-446655440000
  headers:
    RequestId:
      description: >-
        Request correlation ID. Echoes the incoming `x-request-id` header or a
        server-generated ID.
      schema:
        type: string
    RateLimitLimit:
      description: Request limit for the current rate limit window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Remaining requests in the current rate limit window.
      schema:
        type: integer
    RateLimitReset:
      description: Unix timestamp (seconds) when the current rate limit window resets.
      schema:
        type: integer
  securitySchemes:
    API Key:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Enter your API key. Example: Bearer poelis_api_...'

````