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

# List Users by Action

> List members who effectively hold an org-wide IAM action.



## OpenAPI

````yaml GET /orgs/{org_id}/iam/actions/{action}/users
openapi: 3.1.0
info:
  title: Timbal Platform API
  description: Public API documentation for the Timbal platform
  license:
    name: ''
  version: 2.0.0
servers:
  - url: https://api.timbal.ai
    description: Production
  - url: https://api.dev.timbal.ai
    description: Development
security: []
tags:
  - name: ace
    description: Action Control Engine (ACE) operations
  - name: analytics
    description: Org and project analytics
  - name: billing
    description: Subscriptions, usage, and payment-related operations
  - name: content
    description: Re-sign stored content URLs
  - name: files
    description: File operations
  - name: iam
    description: IAM — actions, roles, users, and authorization introspection
  - name: k2
    description: Knowledge Bases v2 operations
  - name: orgs
    description: Organization operations
  - name: projects
    description: Project operations
  - name: runs
    description: Execution operations
  - name: templates
    description: Public project template catalog
  - name: users
    description: Authenticated user profile
paths:
  /orgs/{org_id}/iam/actions/{action}/users:
    get:
      tags:
        - iam
      description: List members who effectively hold an org-wide IAM action.
      operationId: handler
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: string
        - name: action
          in: path
          description: Org-wide IAM action key, for example `roles.manage`.
          required: true
          schema:
            type: string
        - name: user_id
          in: query
          description: |-
            Restrict the report to a single member. Filtering to yourself
            requires only org membership; other members require `users.read`.
          required: false
          schema:
            type:
              - string
              - 'null'
        - name: page_token
          in: query
          description: |-
            Page token for pagination. Pass back the `next_page_token` from the
            previous response.
          required: false
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: Members holding the action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionUsersResBody'
        '403':
          description: Forbidden
        '422':
          description: Unknown or non-org-wide action
      security:
        - bearer_auth: []
components:
  schemas:
    ActionUsersResBody:
      type: object
      required:
        - users
      properties:
        next_page_token:
          type:
            - string
            - 'null'
          description: Token to fetch the next page, or null if this is the last page.
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserAccess'
          description: |-
            Members who effectively hold the action. May hold fewer entries
            than the page window even when more pages exist.
    UserAccess:
      type: object
      description: >-
        A principal with effective access, as returned by the reverse-lookup

        endpoints (`GET /iam/resources/{resource}/users` and

        `GET /iam/actions/{action}/users`).


        Only principals with at least one allowed action appear.
        Deny-beats-allow

        is already applied: an action covered by both an allow and a deny grant

        is not listed. Platform superadmins are not included unless they also

        hold explicit role attachments.
      required:
        - user_id
        - kind
        - allowed_actions
      properties:
        allowed_actions:
          type: array
          items:
            $ref: '#/components/schemas/AllowedAction'
          description: |-
            Actions this principal is effectively allowed to perform, with
            attribution.
        email:
          type:
            - string
            - 'null'
        kind:
          $ref: '#/components/schemas/PrincipalKind'
        name:
          type:
            - string
            - 'null'
        user_id:
          type: string
    AllowedAction:
      type: object
      description: |-
        One action a principal is effectively allowed to perform, with the
        role attachments that grant it.
      required:
        - action
        - via
      properties:
        action:
          type: string
          description: IAM action key (for example `projects.envs.deploy`).
        via:
          type: array
          items:
            $ref: '#/components/schemas/AccessAttribution'
          description: Role attachments contributing a matching allow grant.
    PrincipalKind:
      type: string
      description: |-
        Whether a principal is a person or a platform-managed machine identity
        (for example a project's service credential).
      enum:
        - human
        - service
    AccessAttribution:
      type: object
      description: |-
        Attribution for one allowed action: which role attachment contributed
        the matching allow grant.

        Same shape as [`GrantAttribution`] plus the attachment's expiry —
        "has access until Friday" and "has access" are different findings in
        an access review.
      required:
        - role_id
        - role_name
      properties:
        attachment_scope:
          type:
            - string
            - 'null'
          description: Attachment-level scope in effect, or null when unscoped.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the contributing role attachment expires, or null if permanent.
        grant_resource:
          type:
            - string
            - 'null'
          description: Resource pattern as authored on the role, pre-scope-intersection.
        role_id:
          type: string
        role_name:
          type: string
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      description: >-
        Timbal API key. Obtain your API key from the Timbal platform settings.
        See [Authentication](/api-reference/authentication) for more
        information.

````