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

# List all users and groups with document access

> Returns all users and groups with access to a document in a single paginated call. 

The response includes a list of `principal` objects, where each entry represents a distinct access grant with its own role and settings. A `principal` may appear twice in the response if they have both `direct` access and `folder`-based access to the same document. 




## OpenAPI

````yaml /api/openapi.yaml get /v1/documents/{documentId}/access-list
openapi: 3.1.0
info:
  title: Omni API
  description: >
    The Omni REST API provides programmatic access to your Omni instance for
    managing users, documents, queries, schedules, and more.  
  version: 1.0.0
  contact:
    name: Omni Support
    url: https://docs.omni.co
servers:
  - url: https://{instance}.omniapp.co/api
    description: Production
    variables:
      instance:
        default: blobsrus
        description: Your production Omni instance subdomain
  - url: https://{instance}.playground.exploreomni.dev/api
    description: Playground
    variables:
      instance:
        default: blobsrus
        description: Your playground Omni instance subdomain
security:
  - bearerAuth: []
  - orgApiKey: []
tags:
  - name: AI
    description: AI-powered query generation
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Content
    description: Unified content retrieval (documents and folders)
  - name: Content migration
    description: Export and import dashboards
  - name: Content validator
    description: Validate content against models and perform find/replace operations
  - name: Dashboard downloads
    description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
  - name: Dashboard filters and controls
    description: Read and update dashboard filter and control default values
  - name: dbt
    description: Manage dbt configuration for connections
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: Document favorites
    description: Favorite and unfavorite documents
  - name: Document labels
    description: Apply and manage labels on documents
  - name: Document permissions
    description: Manage document-level access
  - name: Labels
    description: >
      Manage labels in an organization. Labels can be applied to documents and
      folders to help organize and categorize content.


      **Label types:**

      - **Basic labels**: Can be created and managed by any user

      - **Verified labels**: Indicate curated or officially sanctioned content.
      Admin-only.

      - **Homepage labels**: Appear on the organization homepage. Admin-only.
  - name: Folders
    description: Create and organize content folders
  - name: Folder permissions
    description: Manage folder-level access
  - name: Jobs
    description: Check status of asynchronous jobs
  - name: Models
    description: Create and manage data models
  - name: Model branches
    description: Manage model branches and merge changes
  - name: Model git configuration
    description: Manage git configuration for shared models
  - name: Queries
    description: Execute workbook queries
  - name: Schedules
    description: Create and manage scheduled tasks
  - name: Schedule recipients
    description: Manage schedule recipients
  - name: Schema refresh schedules
    description: Manage automated schema refresh schedules for connections
  - name: Topics
    description: Retrieve topic information from models
  - name: Uploads
    description: Manage file uploads
  - name: Users
    description: Manage users
  - name: User attributes
    description: Manage user attribute definitions
  - name: User groups
    description: Manage user groups
  - name: User model roles
    description: Manage model and connection role assignments for users
  - name: User group model roles
    description: Manage model and connection role assignments for user groups
  - name: Uploads
    description: Manage CSV and spreadsheet uploads
paths:
  /v1/documents/{documentId}/access-list:
    get:
      tags:
        - Document permissions
      summary: List all users and groups with document access
      description: >
        Returns all users and groups with access to a document in a single
        paginated call. 


        The response includes a list of `principal` objects, where each entry
        represents a distinct access grant with its own role and settings. A
        `principal` may appear twice in the response if they have both `direct`
        access and `folder`-based access to the same document. 
      operationId: listDocumentAccessList
      parameters:
        - name: documentId
          in: path
          required: true
          schema:
            type: string
          description: >
            The document identifier. To retrieve the ID, navigate to **File >
            Document settings** in the document and then click **Settings**. The
            **Identifier** field contains the document ID.
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Number of results per page (1-100).
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Pagination cursor from a previous response's `pageInfo.nextCursor`.
        - name: sortField
          in: query
          required: false
          schema:
            type: string
            enum:
              - name
              - email
              - role
            default: name
          description: Field to sort results by.
        - name: sortDirection
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
          description: Sort order.
        - name: accessSource
          in: query
          required: false
          schema:
            type: string
            enum:
              - direct
              - folder
          description: |
            Filter by how access was granted:
            - `direct` — Only principals with explicit document permissions
            - `folder` — Only principals with inherited folder permissions
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - user
              - userGroup
          description: |
            Filter by principal type:
            - `user` — Only individual users
            - `userGroup` — Only user groups
      responses:
        '200':
          description: Successfully retrieved access list
          content:
            application/json:
              schema:
                type: object
                properties:
                  principals:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentAccessPrincipal'
                  pageInfo:
                    $ref: '#/components/schemas/PageInfo'
              example:
                principals:
                  - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    name: Jane Smith
                    email: jane@example.com
                    type: user
                    role: EDITOR
                    accessBoost: false
                    accessSource: direct
                    isOwner: false
                  - id: b2c3d4e5-f6a7-8901-bcde-f23456789012
                    name: John Doe
                    email: john@example.com
                    type: user
                    role: VIEWER
                    accessBoost: false
                    accessSource: folder
                    isOwner: false
                    folderInfo:
                      id: c3d4e5f6-a7b8-9012-cdef-345678901234
                      name: Marketing Reports
                      path: /Shared/Marketing Reports
                  - id: d4e5f6a7-b8c9-0123-def0-456789012345
                    name: Data Analysts
                    type: userGroup
                    role: VIEWER
                    accessBoost: false
                    accessSource: direct
                pageInfo:
                  hasNextPage: true
                  nextCursor: eyJuYW1lIjoiSm9obiIsImlkIjoiMTIzIn0=
                  pageSize: 20
                  totalRecords: 47
        '400':
          description: |
            Bad Request. Possible causes:

            - Invalid `pageSize` value (must be 1-100)
            - Invalid `sortField` value
            - Invalid `sortDirection` value
            - Invalid `accessSource` value
            - Invalid `type` value
            - Invalid `cursor` value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidPageSize:
                  summary: Invalid pageSize value
                  value:
                    detail: 'pageSize: Must be between 1 and 100'
                    status: 400
                invalidSortField:
                  summary: Invalid sortField value
                  value:
                    detail: 'sortField: Must be one of: name, email, role'
                    status: 400
        '403':
          description: >
            Forbidden. The user sending the API request must have **Manager**
            permissions for the document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: User does not have permission to manage document permissions
                status: 403
        '404':
          description: Document not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Document with identifier "<documentId>" not found
                status: 404
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - bearerAuth: []
components:
  schemas:
    DocumentAccessPrincipal:
      type: object
      description: Represents a user or group with access to a document.
      properties:
        id:
          type: string
          description: The ID of the user or user group.
        name:
          type: string
          description: Display name of the user or user group.
        email:
          type: string
          description: Email address. Only present for users, not user groups.
        type:
          type: string
          enum:
            - user
            - userGroup
          description: The type of principal.
        role:
          type: string
          enum:
            - VIEWER
            - INTERACTOR
            - EDITOR
            - MANAGER
          description: Permission level assigned to this principal.
        accessBoost:
          type: boolean
          description: Whether elevated access is enabled for this principal.
        accessSource:
          type: string
          enum:
            - direct
            - folder
          description: |
            How access was granted:
            - `direct` — Explicit document permissions
            - `folder` — Inherited from folder permissions
        isOwner:
          type: boolean
          description: >-
            Whether this user owns the document. Only present for users, not
            user groups.
        folderInfo:
          type: object
          description: >-
            Information about the folder that grants access. Only present when
            `accessSource` is `folder`.
          properties:
            id:
              type: string
              description: The ID of the folder.
            name:
              type: string
              description: The name of the folder.
            path:
              type: string
              description: The full path of the folder.
    PageInfo:
      type: object
      description: Pagination information for paginated responses.
      properties:
        hasNextPage:
          type: boolean
          description: Indicates if there are more records available.
        nextCursor:
          type: string
          nullable: true
          description: Cursor for the next page of results. `null` if no more results.
        pageSize:
          type: integer
          description: Number of records per page.
        totalRecords:
          type: integer
          description: Total number of records matching the query.
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
  responses:
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Can be either an [Organization API
        Key](/api/authentication#organization-api-keys) or [Personal Access
        Token (PAT)](/api/authentication#personal-access-tokens-pat).


        Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Requires an [Organization API
        Key](/api/authentication#organization-api-keys). Personal Access Tokens
        (PATs) are not supported for this endpoint.


        Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`

````