Skip to main content
POST
/
groups
cURL
curl --request POST \
  --url https://api.opal.dev/v1/groups \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
}'
{
  "group_id": "f454d283-ca87-4a8a-bdbb-df212eca5353",
  "app_id": "b5a5ca27-0ea3-4d86-9199-2126d57d1fbd",
  "remote_id": "037m2jsg218b2wb",
  "remote_name": "Finance Team",
  "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",
  "max_duration": 120,
  "require_manager_approval": false,
  "require_support_ticket": false
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

CreateGroupInfo Object

Description

The CreateGroupInfo object is used to store creation info for a group.

Usage Example

Use in the POST Groups endpoint.

​
name
string
required

The name of the remote group.

Example:

"mongo-db-prod"

​
group_type
enum<string>
required

The type of the group.

Available options:
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
Example:

"OPAL_GROUP"

​
app_id
string<uuid>
required

The ID of the app for the group.

Example:

"f454d283-ca87-4a8a-bdbb-df212eca5353"

​
description
string

A description of the remote group.

Example:

"Engineering team Okta group."

​
remote_info
object

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.

​
remote_group_id
string
deprecated

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 for details on how to specify this field.

Example:

"00g4fixjd6Bc9w012345"

​
metadata
string
deprecated

Deprecated - use remote_info instead.

JSON metadata about the remote group. Include only for items linked to remote systems. See this guide for details on how to specify this field. The required format is dependent on group_type and should have the following schema:

<style type="text/css"> code {max-height:300px !important} </style> 
{
  "$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\" } }"

​
custom_request_notification
string | null

Custom request notification sent upon request approval.

Maximum length: 800
Example:

"Check your email to register your account."

​
risk_sensitivity_override
enum<string>

Indicates the level of potential impact misuse or unauthorized access may incur.

Available options:
UNKNOWN,
CRITICAL,
HIGH,
MEDIUM,
LOW,
NONE

Response

200 - application/json

The group just created.

Group Object

Description

The Group object is used to represent a group.

Usage Example

Update from the UPDATE Groups endpoint.

​
group_id
string<uuid>
required

The ID of the group.

Example:

"f454d283-ca87-4a8a-bdbb-df212eca5353"

​
app_id
string<uuid>

The ID of the group's app.

Example:

"b5a5ca27-0ea3-4d86-9199-2126d57d1fbd"

​
name
string

The name of the group.

Example:

"API Group"

​
description
string

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."

​
admin_owner_id
string<uuid>

The ID of the owner of the group.

Example:

"7c86c85d-0651-43e2-a748-d69d658418e8"

​
group_leader_user_ids
string<uuid>[]

A list of User IDs for the group leaders of the group

​
remote_id
string

The ID of the remote.

Example:

"google-group-group:037m2jsg218b2wb"

​
remote_name
string

The name of the remote.

Example:

"Finance team"

​
group_type
enum<string>

The type of the group.

Available options:
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
Example:

"OPAL_GROUP"

​
max_duration
integer

The maximum duration for which the group can be requested (in minutes).

Example:

120

​
recommended_duration
integer

The recommended duration for which the group should be requested (in minutes). -1 represents an indefinite duration.

Example:

120

​
extensions_duration_in_minutes
integer

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.

Example:

120

​
require_manager_approval
boolean
deprecated

A bool representing whether or not access requests to the group require manager approval.

Example:

false

​
require_support_ticket
boolean

A bool representing whether or not access requests to the group require an access ticket.

Example:

false

​
require_mfa_to_approve
boolean

A bool representing whether or not to require MFA for reviewers to approve requests for this group.

Example:

false

​
require_mfa_to_request
boolean

A bool representing whether or not to require MFA for requesting access to this group.

Example:

false

​
auto_approval
boolean

A bool representing whether or not to automatically approve requests to this group.

Example:

false

​
request_template_id
string<uuid>

The ID of the associated request template.

Example:

"06851574-e50d-40ca-8c78-f72ae6ab4304"

​
configuration_template_id
string<uuid>

The ID of the associated configuration template.

Example:

"06851574-e50d-40ca-8c78-f72ae6ab4304"

​
group_binding_id
string<uuid>

The ID of the associated group binding.

Example:

"06851574-e50d-40ca-8c78-f72ae6ab4304"

​
is_requestable
boolean

A bool representing whether or not to allow access requests to this group.

Example:

false

​
request_configurations
object[]

A list of request configurations for this group.

Example:
[]
​
request_configuration_list
object[]
deprecated

A list of request configurations for this group. Deprecated in favor of request_configurations.

Example:
[]
​
metadata
string
deprecated

JSON metadata about the remote group. Only set for items linked to remote systems. See this guide for details.

Example:

"{ \"okta_directory_group\": { \"group_id\": \"00g4bs66kwtpe1g12345\" } }"

​
remote_info
object

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.

​
custom_request_notification
string | null

Custom request notification sent to the requester when the request is approved.

Maximum length: 800
Example:

"Check your email to register your account."

​
risk_sensitivity
enum<string>

The risk sensitivity level for the group. When an override is set, this field will match that. Indicates the level of potential impact misuse or unauthorized access may incur.

Available options:
UNKNOWN,
CRITICAL,
HIGH,
MEDIUM,
LOW,
NONE
​
risk_sensitivity_override
enum<string>

Indicates the level of potential impact misuse or unauthorized access may incur.

Available options:
UNKNOWN,
CRITICAL,
HIGH,
MEDIUM,
LOW,
NONE
​
last_successful_sync
object

Information about the last successful sync of this group.

Example:
{
  "id": "7c86c85d-0651-43e2-a748-d69d658418e8",
  "completed_at": "2023-10-01T12:00:00.000Z"
}