> ## Documentation Index > Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Users > List users in an Organization or a specific Workspace within an Organization. If you specify `workspaceId`, the response lists the user's Workspace and Organization roles. If you specify `deploymentId`, the response lists the user's Deployment and Organization roles. If you specify both `workspaceId` and `deploymentId`, the response lists Workspace, Deployment, and Organization roles for users that belong to both the specified Workspace and Deployment. ## OpenAPI ````yaml astro/api/v-1-beta-1/iam/openapi.yaml GET /organizations/{organizationId}/users openapi: 3.0.3 info: contact: {} description: Astro Identity and Access Management (IAM) API title: Astro Identity and Access Management (IAM) API version: v1beta1 servers: - url: https://api.astronomer.io/iam/v1beta1 security: - JWT: [] tags: - description: >- The `user` object represents a user account in your Astro Organization. Astro creates a new `user` object whenever you invite a user by email or add a user to Astro through an identity provider. The object contains all information about a user, including their personal information, roles, and login attempts. It doesn't include attributes for actions that the user completes after they log in, such as updating a Deployment. Make requests to `user` endpoints to manage permissions for existing users both at the Organization and Workspace level. To create new users, make requests to `invite` endpoints instead. name: User - description: >- The `team` object represents an Astro Team, which is a group of users that share the same permissions across your Organization and Workspaces. Make requests to `team` endpoints to create, update, and delete Teams across an Organization. See [Configure Teams on Astro](https://astronomer.io/docs/astro/manage-teams). name: Team - description: >- The `apitoken` object represents a single API token within your Organization. API tokens are used to authenticate automated tools and processes to your Organization. They have varying levels of access to your resources based on their Organization, Workspace, and Deployment roles. See [Workspace API tokens](workspace-api-tokens.md) and [Organization API tokens](organization-api-tokens.md). name: api-token x-group: API Token - description: >- The `invite` object represents the record of a user invite generated by Astro. It includes information both about the inviter and the invitee. Invites can be generated both by manual invitations through the Astro UI and automatic invitations through an identity provider. An `invite` record persists until its associated invite expires. Make requests to `invite` endpoints to create, delete, or audit invites for users across your Organization. See [Manage Organization users](https://astronomer.io/docs/astro/manage-organization-users) and [Manage Workspace users](https://astronomer.io/docs/astro/manage-workspace-users). name: Invite - name: allowed-ip-address-range x-group: Allowed IP Address Range - name: agent-token x-group: Agent Token paths: /organizations/{organizationId}/users: get: tags: - User summary: List users in an Organization description: >- List users in an Organization or a specific Workspace within an Organization. operationId: ListUsers parameters: - description: The ID of the Organization to list users for. in: path name: organizationId required: true schema: type: string - description: >- The ID of the Workspace to filter the list of users for. When specified, the API returns only users belonging to the specified Workspace. in: query name: workspaceId schema: type: string - description: >- The ID of the Deployment to filter the list of users for. When specified, the API returns only users belonging to the specified Deployment. in: query name: deploymentId schema: type: string - description: >- The ID of the DAG to filter the list of users for. When specified, the API returns users belonging to the specified DAG. in: query name: dagId schema: type: string - description: >- The Tags of the DAG to filter the list of users for. When specified, the API returns users belonging to the specified DAG tags. in: query name: dagTags schema: items: type: string type: array - description: Offset for pagination in: query name: offset schema: default: 0 minimum: 0 type: integer - description: Limit for pagination in: query name: limit schema: default: 20 maximum: 1000 minimum: 0 type: integer - description: >- Sorting criteria, each criterion should conform to format 'fieldName:asc' or 'fieldName:desc' in: query name: sorts schema: items: enum: - id:asc - id:desc - username:asc - username:desc - fullName:asc - fullName:desc - createdAt:asc - createdAt:desc - updatedAt:asc - updatedAt:desc type: string type: array responses: '200': content: application/json: schema: $ref: '#/components/schemas/UsersPaginated' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Forbidden '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error security: - JWT: [] components: schemas: UsersPaginated: properties: limit: description: The maximum number of users in one page. example: 10 type: integer offset: description: The offset of the current page of users. example: 0 type: integer totalCount: description: The total number of users. example: 100 type: integer users: description: The list of users in the current page. items: $ref: '#/components/schemas/User' type: array required: - limit - offset - totalCount - users type: object Error: properties: message: type: string requestId: type: string statusCode: maximum: 600 minimum: 400 type: integer required: - message - requestId - statusCode type: object User: properties: avatarUrl: description: The URL for the user's profile image. example: https://avatar.url type: string createdAt: description: >- The time when the user was created in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`. example: '2022-11-22T04:37:12Z' format: date-time type: string dagRoles: description: The user's DAG roles. items: $ref: '#/components/schemas/DagRole' type: array deploymentRoles: description: The user's Deployment roles. items: $ref: '#/components/schemas/DeploymentRole' type: array fullName: description: The user's full name. example: Jane Doe type: string id: description: The user's ID. example: clm9sq6s0000008kz7uvl7yz7 type: string organizationRole: description: The user's Organization role. enum: - ORGANIZATION_OWNER - ORGANIZATION_OBSERVE_ADMIN - ORGANIZATION_OBSERVE_MEMBER - ORGANIZATION_BILLING_ADMIN - ORGANIZATION_MEMBER example: ORGANIZATION_MEMBER type: string status: description: The user's status. enum: - ACTIVE - INACTIVE - PENDING - BANNED example: ACTIVE type: string updatedAt: description: >- The time when the user was updated in UTC, formatted as `YYYY-MM-DDTHH:MM:SSZ`. example: '2022-11-22T04:37:12Z' format: date-time type: string username: description: The user's username. example: user1@company.com type: string workspaceRoles: description: The user's Workspace roles. items: $ref: '#/components/schemas/WorkspaceRole' type: array required: - avatarUrl - createdAt - fullName - id - status - updatedAt - username type: object DagRole: properties: dagId: description: The DAG ID. Required if Tag is not specified. example: my_dag type: string dagTag: description: The DAG tag. Required if DagId is not specified. example: team-a type: string deploymentId: description: The Deployment ID containing the DAG. example: clm8t5u4q000008jq4qoc3031 type: string role: description: The role name (DAG_VIEWER, DAG_AUTHOR, or custom DAG role). example: DAG_VIEWER type: string required: - deploymentId - role type: object DeploymentRole: properties: deploymentId: description: The Deployment ID. example: clm8t5u4q000008jq4qoc3031 type: string role: description: The name of the role for the subject in the Deployment. example: DEPLOYMENT_ADMIN type: string required: - deploymentId - role type: object WorkspaceRole: properties: role: description: The role of the subject in the Workspace. enum: - WORKSPACE_OWNER - WORKSPACE_OPERATOR - WORKSPACE_AUTHOR - WORKSPACE_MEMBER - WORKSPACE_ACCESSOR example: WORKSPACE_MEMBER type: string workspaceId: description: The Workspace ID. example: clm8t5u4q000008jq4qoc3036 type: string required: - role - workspaceId type: object securitySchemes: JWT: scheme: bearer type: http ````