> ## 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 roles > List available user roles in an Organization. ## OpenAPI ````yaml /astro/api/v-1-beta-1/iam/openapi.yaml get /organizations/{organizationId}/roles 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}/roles: get: tags: - Role summary: List roles description: List available user roles in an Organization. operationId: ListRoles parameters: - description: The Organization's ID. in: path name: organizationId required: true schema: type: string - description: Whether to include default Astro roles in the returned list. in: query name: includeDefaultRoles schema: type: boolean - description: Filter the list of roles based on the scope of each role. in: query name: scopeTypes schema: items: enum: - DEPLOYMENT - WORKSPACE - ORGANIZATION - DAG 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 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: - name:asc - name:desc - scopeType:asc - scopeType:desc - description:asc - description:desc - createdAt:asc - createdAt:desc - updatedAt:asc - updatedAt:desc type: string type: array responses: '200': content: application/json: schema: $ref: '#/components/schemas/RolesPaginated' 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 '404': content: application/json: schema: $ref: '#/components/schemas/Error' description: Not Found '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error security: - JWT: [] components: schemas: RolesPaginated: properties: defaultRoles: description: The list of default roles. items: $ref: '#/components/schemas/DefaultRole' type: array limit: description: The number of custom roles returned. example: 1 type: integer offset: description: The offset of the custom roles. example: 1 type: integer roles: description: The list of custom roles. items: $ref: '#/components/schemas/Role' type: array totalCount: description: The total number of custom roles. example: 1 type: integer required: - limit - offset - roles - totalCount type: object Error: properties: message: type: string requestId: type: string statusCode: maximum: 600 minimum: 400 type: integer required: - message - requestId - statusCode type: object DefaultRole: properties: description: description: The role's description. example: Subject can only view deployments. type: string name: description: The role's name. example: Deployment_Viewer type: string permissions: description: The role's permissions. example: - deployment.get items: type: string type: array scopeType: description: The role's scope. enum: - DEPLOYMENT - WORKSPACE - ORGANIZATION - SYSTEM - DAG example: DEPLOYMENT type: string required: - name - permissions - scopeType type: object Role: properties: createdAt: description: The time the role was created. example: '2022-11-22T04:37:12Z' format: date-time type: string createdBy: $ref: '#/components/schemas/BasicSubjectProfile' description: description: The role's description. example: Subject can only view deployments. type: string id: description: The role's ID. example: cluc9tapx000901qn2xrgqdmn type: string name: description: The role's name. example: Deployment_Viewer type: string restrictedWorkspaceIds: description: The IDs of Workspaces that the role is restricted to. example: - cldbvzoi20182g8odxt8ehi5i items: type: string type: array scopeType: description: The role's scope. enum: - DEPLOYMENT - WORKSPACE - ORGANIZATION example: DEPLOYMENT type: string updatedAt: description: The time the role was last updated. example: '2022-11-22T04:37:12Z' format: date-time type: string updatedBy: $ref: '#/components/schemas/BasicSubjectProfile' required: - createdAt - createdBy - id - name - restrictedWorkspaceIds - scopeType - updatedAt - updatedBy type: object BasicSubjectProfile: properties: apiTokenName: description: >- The API token's name. Returned only when `SubjectType` is `SERVICEKEY`. example: my-token type: string avatarUrl: description: >- The URL for the user's profile image. Returned only when `SubjectType` is `USER`. example: https://avatar.url type: string fullName: description: The subject's full name. Returned only when `SubjectType` is `USER`. example: Jane Doe type: string id: description: The subject's ID. example: clm8qv74h000008mlf08scq7k type: string subjectType: description: The subject type. enum: - USER - SERVICEKEY example: USER type: string username: description: The subject's username. Returned only when `SubjectType` is `USER`. example: user1@company.com type: string required: - id type: object securitySchemes: JWT: scheme: bearer type: http ````