> ## Documentation Index > Fetch the complete documentation index at: https://docs.opal.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get groups > Returns a list of groups for your organization. ## OpenAPI ````yaml https://app.opal.dev/openapi.yaml get /groups openapi: 3.1.0 info: contact: email: hello@opal.dev name: Opal Team url: https://www.opal.dev/ description: >- The Opal API is a RESTful API that allows you to interact with the Opal Security platform programmatically. title: Opal API version: '1.0' servers: - description: Production url: https://api.opal.dev/v1 security: [] tags: - name: access-rules description: Operations related to access rules - name: apps description: Operations related to apps - name: bundles description: Operations related to bundles - name: configuration-templates description: Operations related to configuration templates - name: delegations description: Operations related to request reviewer delegations - name: events description: Operations related to events - name: groups description: Operations related to groups - name: group-bindings description: Operations related to group bindings - name: idp-group-mappings description: Operations related to IDP group mappings - name: message-channels description: Operations related to message channels - name: non-human-identities description: Operations related to non-human identities - name: on-call-schedules description: Operations related to on-call schedules - name: owners description: Operations related to owners - name: requests description: Operations related to requests - name: resources description: Operations related to resources - name: sessions description: Operations related to sessions - name: tags description: Operations related to tags - name: tokens description: Operations related to API tokens - name: uars description: Operations related to UARs - name: users description: Operations related to users paths: /groups: get: tags: - groups summary: Get groups description: Returns a list of groups for your organization. operationId: getGroups parameters: - description: The pagination cursor value. example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw explode: true in: query name: cursor required: false schema: type: string style: form - description: Number of results to return per page. Default is 200. example: 200 explode: true in: query name: page_size required: false schema: type: integer maximum: 1000 style: form - description: The group type to filter by. example: OPAL_GROUP explode: true in: query name: group_type_filter required: false schema: $ref: '#/components/schemas/GroupTypeEnum' style: form - description: The group ids to filter by. example: - 4baf8423-db0a-4037-a4cf-f79c60cb67a5 - 1b978423-db0a-4037-a4cf-f79c60cb67b3 explode: false in: query name: group_ids required: false schema: items: example: 1b978423-db0a-4037-a4cf-f79c60cb67b3 format: uuid type: string type: array style: form - description: Group name. example: example-name explode: true in: query name: group_name required: false schema: type: string style: form - description: >- The IDs of the tags to filter by. Returns only groups that have any of these tags applied. in: query name: tag_ids required: false schema: items: type: string format: uuid type: array responses: '200': content: application/json: schema: $ref: '#/components/schemas/PaginatedGroupsList' description: One page worth groups associated with your organization. security: - BearerAuth: [] components: schemas: GroupTypeEnum: description: The type of the group. enum: - ACTIVE_DIRECTORY_GROUP - AWS_SSO_GROUP - DATABRICKS_ACCOUNT_GROUP - DUO_GROUP - GIT_HUB_TEAM - GIT_LAB_GROUP - GOOGLE_GROUPS_GROUP - GOOGLE_GROUPS_GKE_GROUP - LDAP_GROUP - OKTA_GROUP - OKTA_GROUP_RULE - TAILSCALE_GROUP - OPAL_GROUP - OPAL_ACCESS_RULE - AZURE_AD_SECURITY_GROUP - AZURE_AD_MICROSOFT_365_GROUP - CONNECTOR_GROUP - SNOWFLAKE_ROLE - WORKDAY_USER_SECURITY_GROUP - PAGERDUTY_ON_CALL_SCHEDULE - INCIDENTIO_ON_CALL_SCHEDULE - ROOTLY_ON_CALL_SCHEDULE - DEVIN_GROUP - GIT_HUB_ENTERPRISE_TEAM - GRAFANA_TEAM - CLICKHOUSE_ROLE - TWINGATE_GROUP - TWINGATE_GROUP_SYNCED example: OPAL_GROUP type: string PaginatedGroupsList: example: next: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw previous: cj1sZXdwd2VycWVtY29zZnNkc2NzUWxNMEUxTXk0ME16UXpNallsTWtJ results: - group_id: f454d283-ca87-4a8a-bdbb-df212eca5353 app_id: b5a5ca27-0ea3-4d86-9199-2126d57d1fbd name: Payments Production Admin description: >- This group represents Active Directory group "Payments Production Admin". We use this AD group to facilitate staging deployments and qualifying new releases. admin_owner_id: 7c86c85d-0651-43e2-a748-d69d658418e8 group_leader_user_ids: - 7c86c85d-0651-43e2-a748-d69d658418e8 remote_id: 037m2jsg218b2wb remote_name: Finance Team group_type: ACTIVE_DIRECTORY_GROUP max_duration: 120 recommended_duration: 60 extensions_duration_in_minutes: 60 require_manager_approval: false require_support_ticket: false require_mfa_to_approve: false require_mfa_to_request: false auto_approval: false is_requestable: true - group_id: 99d0b81d-14be-4cf6-bd27-348b4af1d11b app_id: a7c3e291-1234-4abc-9def-1234567890ab name: Integrations On-Call description: >- Manages the Integrations Team on-call privileged resources. This group is automatically synced with the on-call rotation defined in PagerDuty. admin_owner_id: 4220bc12-ab8a-4b5d-be7b-f6bbcf9159f3 group_leader_user_ids: [] remote_id: pagerduty-schedule:P123XYZ remote_name: Integrations On-Call group_type: PAGERDUTY_ON_CALL_SCHEDULE max_duration: 360 recommended_duration: 120 extensions_duration_in_minutes: 0 require_manager_approval: false require_support_ticket: true require_mfa_to_approve: false require_mfa_to_request: false auto_approval: false is_requestable: true properties: next: description: >- The cursor with which to continue pagination if additional result pages exist. example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw nullable: true type: string previous: description: The cursor used to obtain the current result page. example: cj1sZXdwd2VycWVtY29zZnNkc2NzUWxNMEUxTXk0ME16UXpNallsTWtJ nullable: true type: string results: items: $ref: '#/components/schemas/Group' type: array type: object required: - results Group: description: |- # Group Object ### Description The `Group` object is used to represent a group. ### Usage Example Update from the `UPDATE Groups` endpoint. example: group_id: f454d283-ca87-4a8a-bdbb-df212eca5353 app_id: b5a5ca27-0ea3-4d86-9199-2126d57d1fbd name: Payments Production Admin description: >- This group represents Active Directory group "Payments Production Admin". We use this AD group to facilitate staging deployments and qualifying new releases. admin_owner_id: 7c86c85d-0651-43e2-a748-d69d658418e8 group_leader_user_ids: - 7c86c85d-0651-43e2-a748-d69d658418e8 remote_id: 037m2jsg218b2wb remote_name: Finance Team group_type: ACTIVE_DIRECTORY_GROUP max_duration: 120 recommended_duration: 60 extensions_duration_in_minutes: 60 require_manager_approval: false require_support_ticket: false require_mfa_to_approve: false require_mfa_to_request: false auto_approval: false is_requestable: true properties: group_id: description: The ID of the group. example: f454d283-ca87-4a8a-bdbb-df212eca5353 format: uuid type: string app_id: description: The ID of the group's app. example: b5a5ca27-0ea3-4d86-9199-2126d57d1fbd format: uuid type: string name: description: The name of the group. example: API Group type: string description: description: A description of the group. example: >- This group represents Active Directory group "Payments Production Admin". We use this AD group to facilitate staging deployments and qualifying new releases. type: string admin_owner_id: description: The ID of the owner of the group. example: 7c86c85d-0651-43e2-a748-d69d658418e8 format: uuid type: string group_leader_user_ids: description: A list of User IDs for the group leaders of the group items: type: string format: uuid type: array remote_id: description: The ID of the remote. example: google-group-group:037m2jsg218b2wb type: string remote_name: description: The name of the remote. example: Finance team type: string group_type: $ref: '#/components/schemas/GroupTypeEnum' max_duration: description: >- The maximum duration for which the group can be requested (in minutes). type: integer example: 120 recommended_duration: description: >- The recommended duration for which the group should be requested (in minutes). -1 represents an indefinite duration. type: integer example: 120 extensions_duration_in_minutes: description: >- The duration for which access can be extended (in minutes). Set to 0 to disable extensions. When > 0, extensions are enabled for the specified duration. type: integer example: 120 require_manager_approval: description: >- A bool representing whether or not access requests to the group require manager approval. example: false type: boolean deprecated: true require_support_ticket: description: >- A bool representing whether or not access requests to the group require an access ticket. example: false type: boolean require_mfa_to_approve: description: >- A bool representing whether or not to require MFA for reviewers to approve requests for this group. example: false type: boolean require_mfa_to_request: description: >- A bool representing whether or not to require MFA for requesting access to this group. example: false type: boolean auto_approval: description: >- A bool representing whether or not to automatically approve requests to this group. example: false type: boolean request_template_id: description: The ID of the associated request template. example: 06851574-e50d-40ca-8c78-f72ae6ab4304 format: uuid type: string configuration_template_id: description: The ID of the associated configuration template. example: 06851574-e50d-40ca-8c78-f72ae6ab4304 format: uuid type: string group_binding_id: description: The ID of the associated group binding. example: 06851574-e50d-40ca-8c78-f72ae6ab4304 format: uuid type: string is_requestable: description: >- A bool representing whether or not to allow access requests to this group. example: false type: boolean request_configurations: description: A list of request configurations for this group. example: [] type: array items: $ref: '#/components/schemas/RequestConfiguration' request_configuration_list: description: >- A list of request configurations for this group. Deprecated in favor of `request_configurations`. deprecated: true example: [] type: array items: $ref: '#/components/schemas/RequestConfiguration' metadata: description: >- JSON metadata about the remote group. Only set for items linked to remote systems. See [this guide](https://docs.opal.dev/reference/end-system-objects) for details. deprecated: true example: '{ "okta_directory_group": { "group_id": "00g4bs66kwtpe1g12345" } }' type: string remote_info: $ref: '#/components/schemas/GroupRemoteInfo' custom_request_notification: description: >- Custom request notification sent to the requester when the request is approved. type: string maxLength: 800 nullable: true example: Check your email to register your account. risk_sensitivity: description: >- The risk sensitivity level for the group. When an override is set, this field will match that. readOnly: true allOf: - $ref: '#/components/schemas/RiskSensitivityEnum' risk_sensitivity_override: allOf: - $ref: '#/components/schemas/RiskSensitivityEnum' last_successful_sync: $ref: '#/components/schemas/SyncTask' readOnly: true description: Information about the last successful sync of this group. required: - group_id type: object RequestConfiguration: description: >- # Request Configuration Object ### Description The `RequestConfiguration` object is used to represent a request configuration. ### Usage Example Returned from the `GET Request Configurations` endpoint. example: request_configuration_id: 7c86c85d-0651-43e2-a748-d69d658418e8 organization_id: w86c85d-0651-43e2-a748-d69d658418e8 created_at: '2021-01-06T20:00:00.000Z' updated_at: '2021-01-06T20:00:00.000Z' condition: group_id: 1b978423-db0a-4037-a4cf-f79c60cb67b3 allow_requests: true auto_approval: false require_mfa_to_request: false max_duration_minutes: 120 recommended_duration_minutes: 120 require_support_ticket: false reviewer_stages: - reviewer_stage_id: 7c86c85d-0651-43e2-a748-d69d658418e8 owner_ids: - 37cb7e41-12ba-46da-92ff-030abe0450b1 - 37cb7e41-12ba-46da-92ff-030abe0450b2 stage: 1 priority: 1 type: object properties: condition: $ref: '#/components/schemas/Condition' description: The condition for the request configuration. allow_requests: description: >- A bool representing whether or not to allow requests for this resource. example: true type: boolean auto_approval: description: >- A bool representing whether or not to automatically approve requests for this resource. example: false type: boolean require_mfa_to_request: description: >- A bool representing whether or not to require MFA for requesting access to this resource. example: false type: boolean max_duration_minutes: description: >- The maximum duration for which the resource can be requested (in minutes). type: integer example: 120 recommended_duration_minutes: description: >- The recommended duration for which the resource should be requested (in minutes). -1 represents an indefinite duration. type: integer example: 120 require_support_ticket: description: >- A bool representing whether or not access requests to the resource require an access ticket. example: false type: boolean extensions_duration_in_minutes: description: >- The duration for which access can be extended (in minutes). Set to 0 to disable extensions. When > 0, extensions are enabled for the specified duration. type: integer example: 120 request_template_id: description: The ID of the associated request template. example: 06851574-e50d-40ca-8c78-f72ae6ab4304 format: uuid type: string reviewer_stages: description: The list of reviewer stages for the request configuration. items: $ref: '#/components/schemas/ReviewerStage' type: array priority: description: The priority of the request configuration. example: 1 type: integer required: - organization_id - allow_requests - auto_approval - require_mfa_to_request - require_support_ticket - priority GroupRemoteInfo: description: >- Information that defines the remote group. This replaces the deprecated remote_id and metadata fields. If remote_info is provided, a group will be imported into Opal. For group types that support group creation through Opal, a new group will be created if remote_info is not provided. properties: active_directory_group: description: Remote info for Active Directory group. properties: group_id: description: The id of the Google group. example: 01fa7402-01d8-103b-8deb-5f3a0ab7884 type: string type: object required: - group_id tailscale_group: description: Remote info for Tailscale group. properties: group_id: description: The id of the Tailscale group. example: 898931321 type: string type: object required: - group_id twingate_group: description: Remote info for Twingate group. properties: group_id: description: The id of the Twingate group. example: R3JvdXA6MTIzNA== type: string type: object required: - group_id twingate_group_synced: description: Remote info for Twingate synced group. properties: group_id: description: The id of the Twingate synced group. example: R3JvdXA6MTIzNA== type: string type: object required: - group_id aws_sso_group: description: Remote info for AWS SSO group. properties: group_id: description: The id of the AWS SSO group. example: 898931321 type: string type: object required: - group_id databricks_account_group: description: Remote info for Databricks account group. properties: group_id: description: The id of the Databricks account group. example: 898931321 type: string type: object required: - group_id connector_group: description: Remote info for Connector group. properties: group_id: description: The id of the Connector group. example: 898931321 type: string type: object required: - group_id github_team: description: Remote info for GitHub team. properties: team_id: deprecated: true description: The id of the GitHub team. example: 898931321 type: string team_slug: description: The slug of the GitHub team. example: opal-security type: string org_name: description: GitHub team's org name, required only for Enterprise type: string type: object required: - team_slug github_enterprise_team: description: Remote info for GitHub Enterprise team. properties: team_slug: description: The slug of the GitHub Enterprise team. example: opal-security type: string type: object required: - team_slug gitlab_group: description: Remote info for Gitlab group. properties: group_id: description: The id of the Gitlab group. example: 898931321 type: string type: object required: - group_id google_group: description: Remote info for Google group. properties: group_id: description: The id of the Google group. example: 1y6w882181n7sg type: string type: object required: - group_id ldap_group: description: Remote info for LDAP group. properties: group_id: description: The id of the LDAP group. example: 01fa7402-01d8-103b-8deb-5f3a0ab7884 type: string type: object required: - group_id okta_group: description: Remote info for Okta Directory group. properties: group_id: description: The id of the Okta Directory group. example: 00gjs33pe8rtmRrp3rd6 type: string type: object required: - group_id duo_group: description: Remote info for Duo Security group. properties: group_id: description: The id of the Duo Security group. example: DSRD8W89B9DNDBY4RHAC type: string type: object required: - group_id azure_ad_security_group: description: Remote info for Microsoft Entra ID Security group. properties: group_id: description: The id of the Microsoft Entra ID Security group. example: 01fa7402-01d8-103b-8deb-5f3a0ab7884 type: string type: object required: - group_id azure_ad_microsoft_365_group: description: Remote info for Microsoft Entra ID Microsoft 365 group. properties: group_id: description: The id of the Microsoft Entra ID Microsoft 365 group. example: 01fa7402-01d8-103b-8deb-5f3a0ab7884 type: string type: object required: - group_id snowflake_role: description: Remote info for Snowflake role. properties: role_id: description: The id of the Snowflake role. example: 01fa7402-01d8-103b-8deb-5f3a0ab7884 type: string type: object required: - role_id okta_group_rule: description: Remote info for Okta Directory group rule. properties: rule_id: description: The id of the Okta group rule. example: 0pr3f7zMZZHPgUoWO0g4 type: string type: object required: - rule_id workday_user_security_group: description: Remote info for Workday User Security group. properties: group_id: description: The id of the Workday User Security group. example: 123abc456def type: string type: object required: - group_id pagerduty_on_call_schedule: description: Remote info for PagerDuty on-call schedule group. properties: schedule_id: description: The id of the PagerDuty on-call schedule. example: PNZNINN type: string type: object required: - schedule_id incidentio_on_call_schedule: description: Remote info for Incident.io on-call schedule group. properties: schedule_id: description: The id of the Incident.io on-call schedule. example: 01HZ8XQM9ZQX8RKMZQ8ZQX8RK type: string type: object required: - schedule_id rootly_on_call_schedule: description: Remote info for Rootly on-call schedule group. properties: schedule_id: description: The id of the Rootly on-call schedule. example: 01HZ8XQM9ZQX8RKMZQ8ZQX8RK type: string type: object required: - schedule_id devin_group: description: Remote info for Devin group. properties: group_name: description: The name of the Devin group. example: devin-group-01 type: string type: object required: - group_name clickhouse_role: description: Remote info for ClickHouse role. properties: role_id: description: The name of the ClickHouse role. example: my_clickhouse_role type: string type: object required: - role_id grafana_team: description: Remote info for Grafana team. properties: team_id: description: The ID of the team. example: 2323 type: string type: object required: - team_id type: object RiskSensitivityEnum: type: string description: >- Indicates the level of potential impact misuse or unauthorized access may incur. enum: - UNKNOWN - CRITICAL - HIGH - MEDIUM - LOW - NONE SyncTask: type: object description: >- Represents a sync task that has been completed, either successfully or with errors. properties: id: description: The ID of the sync task. example: 7c86c85d-0651-43e2-a748-d69d658418e8 format: uuid type: string completed_at: description: The time when the sync task was completed. example: '2023-10-01T12:00:00.000Z' type: string format: date-time required: - id - completed_at example: id: 7c86c85d-0651-43e2-a748-d69d658418e8 completed_at: '2023-10-01T12:00:00.000Z' Condition: description: |- # Condition Object ### Description The `Condition` object is used to represent a condition. ### Usage Example Used to match request configurations to users in `RequestConfiguration` example: group_ids: - 1b978423-db0a-4037-a4cf-f79c60cb67b3 type: object properties: group_ids: description: The list of group IDs to match. example: - 1b978423-db0a-4037-a4cf-f79c60cb67b3 items: type: string format: uuid type: array role_remote_ids: description: The list of role remote IDs to match. example: - arn:aws:iam::590304332660:role/AdministratorAccess type: array items: type: string ReviewerStage: description: A reviewer stage. example: owner_ids: - 7870617d-e72a-47f5-a84c-693817ab4567 - 1520617d-e72a-47f5-a84c-693817ab48ad2 service_user_ids: - 7870617d-e72a-47f5-a84c-693817ab4568 properties: require_manager_approval: description: Whether this reviewer stage should require manager approval. example: false type: boolean require_admin_approval: description: Whether this reviewer stage should require admin approval. example: false type: boolean operator: description: >- The operator of the reviewer stage. Admin and manager approval are also treated as reviewers. enum: - AND - OR example: AND type: string owner_ids: description: The IDs of owners assigned as reviewers for this stage. items: type: string format: uuid type: array service_user_ids: description: The IDs of service users assigned as reviewers for this stage. items: type: string format: uuid type: array type: object required: - operator - require_manager_approval - owner_ids - stage securitySchemes: BearerAuth: scheme: bearer type: http ````