> ## 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. # Post groups > Creates an Opal group or [imports a remote group](https://docs.opal.dev/reference/end-system-objects). ## OpenAPI ````yaml https://app.opal.dev/openapi.yaml post /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: post: tags: - groups description: >- Creates an Opal group or [imports a remote group](https://docs.opal.dev/reference/end-system-objects). operationId: createGroup requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGroupInfo' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Group' description: The group just created. security: - BearerAuth: [] components: schemas: CreateGroupInfo: description: |- # CreateGroupInfo Object ### Description The `CreateGroupInfo` object is used to store creation info for a group. ### Usage Example Use in the `POST Groups` endpoint. example: remote_group_id: 00g4fixjd6Bc9w0TT5d7 name: Engineering Team description: Engineering team Okta group. group_type: OKTA_GROUP metadata: '{ "okta_directory_group": { "group_id": "00g4bs66kwtpe1g12345" } }' app_id: f454d283-ca87-4a8a-bdbb-df212eca5353 properties: name: description: The name of the remote group. example: mongo-db-prod type: string description: description: A description of the remote group. example: Engineering team Okta group. type: string group_type: $ref: '#/components/schemas/GroupTypeEnum' app_id: description: The ID of the app for the group. example: f454d283-ca87-4a8a-bdbb-df212eca5353 format: uuid type: string remote_info: $ref: '#/components/schemas/GroupRemoteInfo' remote_group_id: deprecated: true description: >- Deprecated - use remote_info instead. The ID of the group on the remote system. Include only for items linked to remote systems. See [this guide](https://docs.opal.dev/reference/end-system-objects) for details on how to specify this field. example: 00g4fixjd6Bc9w012345 type: string metadata: deprecated: true description: >- Deprecated - use remote_info instead. JSON metadata about the remote group. Include only for items linked to remote systems. See [this guide](https://docs.opal.dev/reference/end-system-objects) for details on how to specify this field. The required format is dependent on group_type and should have the following schema: ```json { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Group Metadata", "properties": { "ad_group": { "properties": { "object_guid": { "type": "string" } }, "required": ["object_guid"], "additionalProperties": false, "type": "object", "title": "Active Directory Group" }, "duo_group": { "properties": { "group_id": { "type": "string" } }, "required": ["group_id"], "additionalProperties": false, "type": "object", "title": "Duo Group" }, "git_hub_team": { "properties": { "org_name": { "type": "string" }, "team_slug": { "type": "string" } }, "required": ["org_name", "team_slug"], "additionalProperties": false, "type": "object", "title": "GitHub Team" }, "google_groups_group": { "properties": { "group_id": { "type": "string" } }, "required": ["group_id"], "additionalProperties": false, "type": "object", "title": "Google Groups Group" }, "ldap_group": { "properties": { "group_uid": { "type": "string" } }, "required": ["group_uid"], "additionalProperties": false, "type": "object", "title": "LDAP Group" }, "okta_directory_group": { "properties": { "group_id": { "type": "string" } }, "required": ["group_id"], "additionalProperties": false, "type": "object", "title": "Okta Directory Group" } }, "additionalProperties": false, "minProperties": 1, "maxProperties": 1, "type": "object" } ``` example: '{ "okta_directory_group": { "group_id": "00g4bs66kwtpe1g12345" } }' type: string custom_request_notification: description: Custom request notification sent upon request approval. type: string maxLength: 800 nullable: true example: Check your email to register your account. risk_sensitivity_override: allOf: - $ref: '#/components/schemas/RiskSensitivityEnum' required: - name - group_type - app_id type: object 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 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 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 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 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 ````