Groups

The Groups API provides operations to manage Okta Groups and their user members for your organization.

List all Groups
OAuth 2.0: okta.groups.read

Lists all groups with pagination support. A subset of groups can be returned that match a supported filter expression or query.

Request
query Parameters
q
string

Searches the name property of groups for matching value

filter
string

Filter expression for groups

after
string

Specifies the pagination cursor for the next page of groups

limit
integer <int32>
Default: 10000

Specifies the number of group results in a page

expand
string

If specified, it causes additional metadata to be included in the response.

search
string

Searches for groups with a supported filtering expression for all attributes except for _embedded, _links, and objectClass

sortBy
string

Specifies field to sort by and can be any single property (for search queries only).

Example: sortBy=lastUpdated
sortOrder
string
Default: "asc"

Specifies sort order asc or desc (for search queries only). This parameter is ignored if sortBy is not present. Groups with the same value for the sortBy parameter are ordered by id.

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/groups
Request samples
Response samples
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "lastMembershipUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "objectClass": [
      ],
    • "profile": {
      },
    • "type": "APP_GROUP",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Create a Group
OAuth 2.0: okta.groups.manage

Creates a new group with OKTA_GROUP type

Request
Request Body schema: application/json
required
object (GroupProfile)
description
string
name
string
property name*
additional property
any
type
string (GroupType)
Enum: "APP_GROUP" "BUILT_IN" "OKTA_GROUP"
Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/groups
Request samples
application/json
{
  • "profile": {
    • "description": "string",
    • "name": "string"
    },
  • "type": "APP_GROUP"
}
Response samples
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "lastMembershipUpdated": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "objectClass": [
    • "string"
    ],
  • "profile": {
    • "description": "string",
    • "name": "string"
    },
  • "type": "APP_GROUP",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      },
    • "apps": {
      },
    • "logo": [
      ],
    • "source": {
      },
    • "users": {
      }
    }
}

List all Group Rules
OAuth 2.0: okta.groups.read

Lists all group rules

Request
query Parameters
limit
integer <int32>
Default: 50

Specifies the number of rule results in a page

after
string

Specifies the pagination cursor for the next page of rules

search
string

Specifies the keyword to search fules for

expand
string

If specified as groupIdToGroupNameMap, then show group names

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/groups/rules
Request samples
Response samples
application/json
[
  • {
    • "actions": {
      },
    • "conditions": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "name": "string",
    • "status": "ACTIVE",
    • "type": "string"
    }
]

Create a Group Rule
OAuth 2.0: okta.groups.manage

Creates a group rule to dynamically add users to the specified group if they match the condition

Request
Request Body schema: application/json
required
object (GroupRuleAction)
object (GroupRuleGroupAssignment)
groupIds
Array of strings
object (GroupRuleConditions)
object (GroupRuleExpression)
type
string
value
string
object (GroupRulePeopleCondition)
object (GroupRuleGroupCondition)
object (GroupRuleUserCondition)
name
string
status
string (GroupRuleStatus)
Enum: "ACTIVE" "INACTIVE" "INVALID"
type
string
Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/groups/rules
Request samples
application/json
{
  • "actions": {
    • "assignUserToGroups": {
      }
    },
  • "conditions": {
    • "expression": {
      },
    • "people": {
      }
    },
  • "name": "string",
  • "status": "ACTIVE",
  • "type": "string"
}
Response samples
application/json
{
  • "actions": {
    • "assignUserToGroups": {
      }
    },
  • "conditions": {
    • "expression": {
      },
    • "people": {
      }
    },
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "status": "ACTIVE",
  • "type": "string"
}

Retrieve a Group Rule
OAuth 2.0: okta.groups.read

Retrieves a specific group rule by groupRuleId

Request
path Parameters
groupRuleId
required
string

The id of the group rule

Example: 0pr3f7zMZZHPgUoWO0g4
query Parameters
expand
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/groups/rules/{groupRuleId}
Request samples
Response samples
application/json
{
  • "actions": {
    • "assignUserToGroups": {
      }
    },
  • "conditions": {
    • "expression": {
      },
    • "people": {
      }
    },
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "status": "ACTIVE",
  • "type": "string"
}

Replace a Group Rule
OAuth 2.0: okta.groups.manage

Replaces a group rule. Only INACTIVE rules can be updated.

Request
path Parameters
groupRuleId
required
string

The id of the group rule

Example: 0pr3f7zMZZHPgUoWO0g4
Request Body schema: application/json
required
object (GroupRuleAction)
object (GroupRuleGroupAssignment)
groupIds
Array of strings
object (GroupRuleConditions)
object (GroupRuleExpression)
type
string
value
string
object (GroupRulePeopleCondition)
object (GroupRuleGroupCondition)
object (GroupRuleUserCondition)
name
string
status
string (GroupRuleStatus)
Enum: "ACTIVE" "INACTIVE" "INVALID"
type
string
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/groups/rules/{groupRuleId}
Request samples
application/json
{
  • "actions": {
    • "assignUserToGroups": {
      }
    },
  • "conditions": {
    • "expression": {
      },
    • "people": {
      }
    },
  • "name": "string",
  • "status": "ACTIVE",
  • "type": "string"
}
Response samples
application/json
{
  • "actions": {
    • "assignUserToGroups": {
      }
    },
  • "conditions": {
    • "expression": {
      },
    • "people": {
      }
    },
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "status": "ACTIVE",
  • "type": "string"
}

Delete a group Rule
OAuth 2.0: okta.groups.manage

Deletes a specific group rule by groupRuleId

Request
path Parameters
groupRuleId
required
string

The id of the group rule

Example: 0pr3f7zMZZHPgUoWO0g4
query Parameters
removeUsers
boolean

Indicates whether to keep or remove users from groups assigned by this rule.

Responses
202

Accepted

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/groups/rules/{groupRuleId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Activate a Group Rule
OAuth 2.0: okta.groups.manage

Activates a specific group rule by groupRuleId

Request
path Parameters
groupRuleId
required
string

The id of the group rule

Example: 0pr3f7zMZZHPgUoWO0g4
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/groups/rules/{groupRuleId}/lifecycle/activate
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Deactivate a Group Rule
OAuth 2.0: okta.groups.manage

Deactivates a specific group rule by groupRuleId

Request
path Parameters
groupRuleId
required
string

The id of the group rule

Example: 0pr3f7zMZZHPgUoWO0g4
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/groups/rules/{groupRuleId}/lifecycle/deactivate
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Retrieve a Group
OAuth 2.0: okta.groups.read

Retrieves a group by groupId

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/groups/{groupId}
Request samples
Response samples
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "lastMembershipUpdated": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "objectClass": [
    • "string"
    ],
  • "profile": {
    • "description": "string",
    • "name": "string"
    },
  • "type": "APP_GROUP",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      },
    • "apps": {
      },
    • "logo": [
      ],
    • "source": {
      },
    • "users": {
      }
    }
}

Replace a Group
OAuth 2.0: okta.groups.manage

Replaces the profile for a group with OKTA_GROUP type

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
Request Body schema: application/json
required
object (GroupProfile)
description
string
name
string
property name*
additional property
any
type
string (GroupType)
Enum: "APP_GROUP" "BUILT_IN" "OKTA_GROUP"
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/groups/{groupId}
Request samples
application/json
{
  • "profile": {
    • "description": "string",
    • "name": "string"
    },
  • "type": "APP_GROUP"
}
Response samples
application/json
{
  • "created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "lastMembershipUpdated": "2019-08-24T14:15:22Z",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "objectClass": [
    • "string"
    ],
  • "profile": {
    • "description": "string",
    • "name": "string"
    },
  • "type": "APP_GROUP",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      },
    • "apps": {
      },
    • "logo": [
      ],
    • "source": {
      },
    • "users": {
      }
    }
}

Delete a Group
OAuth 2.0: okta.groups.manage

Deletes a group with OKTA_GROUP type

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/groups/{groupId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

List all Assigned Applications
OAuth 2.0: okta.groups.read

Lists all applications that are assigned to a group

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
query Parameters
after
string

Specifies the pagination cursor for the next page of apps

limit
integer <int32>
Default: 20

Specifies the number of app results for a page

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/groups/{groupId}/apps
Request samples
Response samples
application/json
[
  • {
    • "accessibility": {
      },
    • "created": "2019-08-24T14:15:22Z",
    • "features": [
      ],
    • "id": "string",
    • "label": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "licensing": {
      },
    • "profile": {
      },
    • "signOnMode": "AUTO_LOGIN",
    • "status": "ACTIVE",
    • "visibility": {
      },
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

List all Group Owners
OAuth 2.0: okta.groups.read

Lists all owners for a specific group

Note: This API is only available if you're subscribed to Okta Identity Governance. Contact your Customer Success Manager or Account Executive for more information.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
query Parameters
filter
string

SCIM Filter expression for group owners. Allows to filter owners by type.

after
string

Specifies the pagination cursor for the next page of owners

limit
integer <int32>
Default: 1000

Specifies the number of owner results in a page

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/groups/{groupId}/owners
Request samples
Response samples
application/json
[
  • {
    • "id": "00g1gae1k0znUcLuU0h8",
    • "type": "GROUP",
    • "resolved": true,
    • "originId": "null",
    • "originType": "OKTA_DIRECTORY",
    • "displayName": "Product & Engineering",
    • "lastUpdated": "2023-03-29 18:18:37.0"
    }
]

Assign a Group Owner
OAuth 2.0: okta.groups.manage

Assigns a group owner

Note: This API is only available if you're subscribed to Okta Identity Governance. Contact your Customer Success Manager or Account Executive for more information.

Request
path Parameters
groupId
required
string
Request Body schema: application/json
required
id
string

The id of the group owner

type
string (GroupOwnerType)

The entity type of the owner

Enum: "GROUP" "USER"
Responses
201

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/groups/{groupId}/owners
Request samples
application/json
{
  • "id": "00u1cmc03xjzePoWD0h8",
  • "type": "USER"
}
Response samples
application/json
{
  • "id": "00u1cmc03xjzePoWD0h8",
  • "type": "USER",
  • "resolved": true,
  • "originId": null,
  • "originType": "OKTA_DIRECTORY",
  • "displayName": "Oliver Putnam",
  • "lastUpdated": "Wed Mar 29 18:34:31 UTC 2023"
}

Delete a Group Owner
OAuth 2.0: okta.groups.manage

Deletes a group owner from a specific group

Note: This API is only available if you're subscribed to Okta Identity Governance. Contact your Customer Success Manager or Account Executive for more information.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
ownerId
required
string

The id of the group owner

Example: 00u1emaK22TWRYd3TtG
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/groups/{groupId}/owners/{ownerId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

List all Member Users
OAuth 2.0: okta.groups.read

Lists all users that are a member of a group

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
query Parameters
after
string

Specifies the pagination cursor for the next page of users

limit
integer <int32>
Default: 1000

Specifies the number of user results in a page

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/groups/{groupId}/users
Request samples
Response samples
application/json
[
  • {
    • "activated": "2019-08-24T14:15:22Z",
    • "created": "2019-08-24T14:15:22Z",
    • "credentials": {
      },
    • "id": "string",
    • "lastLogin": "2019-08-24T14:15:22Z",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "passwordChanged": "2019-08-24T14:15:22Z",
    • "profile": {
      },
    • "realmId": "guo1bfiNtSnZYILxO0g4",
    • "status": "ACTIVE",
    • "statusChanged": "2019-08-24T14:15:22Z",
    • "transitioningToStatus": "ACTIVE",
    • "type": {
      },
    • "_embedded": {
      },
    • "_links": {
      }
    }
]

Assign a User
OAuth 2.0: okta.groups.manage

Assigns a user to a group with 'OKTA_GROUP' type

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
userId
required
string

ID of an existing Okta user

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/groups/{groupId}/users/{userId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Unassign a User
OAuth 2.0: okta.groups.manage

Unassigns a user from a group with 'OKTA_GROUP' type

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
userId
required
string

ID of an existing Okta user

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/groups/{groupId}/users/{userId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}