Groups

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

List all groups
OAuth 2.0: okta.groups.read

Lists all groups with pagination support.

The number of groups returned depends on the specified limit, if you have a search, filter, and/or query parameter set, and if that parameter is not null. We recommend using a limit less than or equal to 200.

A subset of groups can be returned that match a supported filter expression, query, or search criteria.

Note: Results from the filter or query parameter are driven from an eventually consistent datasource. The synchronization lag is typically less than one second. See Filtering for more information on expressions.

Request
query Parameters
q
string

Finds a group that matches the name property

Note: Paging and searching are currently mutually exclusive. You can't page a query. The default limit for a query is 300 results. Query is intended for an auto-complete picker use case where users refine their search string to constrain the results.

Example: q=West&limit=10
filter
string

Filter expression for groups

Note: All filters must be URL encoded. For example, filter=lastUpdated gt "2013-06-01T00:00:00.000Z" is encoded as filter=lastUpdated%20gt%20%222013-06-01T00:00:00.000Z%22.

Examples:
filter=id eq "00g1emaKYZTWRYYRRTSK"
filter=type eq "OKTA_GROUP"
filter=type eq "OKTA_GROUP" and lastUpdated gt "2016-11-11T00:00:00.000Z"
filter=type eq "OKTA_GROUP" and (lastUpdated lt "2015-11-11T00:00:00.000Z" or lastMembershipUpdated lt "2015-11-11T00:00:00.000Z")
after
string

Specifies the pagination cursor for the next page of groups. The after cursor should be treated as an opaque value and obtained through the next link relation. See Pagination.

limit
integer <int32> <= 10000

Specifies the number of group results in a page.

Don't write code that depends on the default or maximum value, as it might change. If you receive an HTTP 500 status code, you likely exceeded the request timeout. Retry your request with a smaller limit and page the results.

The Okta default Everyone group isn't returned for users with a group Admin role.

Note: We strongly encourage using a limit that's less than or equal to 200. Any number greater than 200 affects performance and accuracy.

expand
string

If specified, additional metadata is included in the response. Possible values are stats and app. This additional metadata is listed in the _embedded key of the response.

Note: You can use the stats value to return the number of users within a group. This is listed as the _embedded.stats.usersCount value in the response. See this Knowledge Base article for more information and an example.

search
string

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

Search currently performs a startsWith match but it should be considered an implementation detail and might change without notice in the future. This operation supports pagination.

Using search requires URL encoding, for example, search=type eq "OKTA_GROUP" is encoded as search=type+eq+%22OKTA_GROUP%22.

This operation searches many properties: * Any group profile property, including imported app group profile properties. * The top-level properties id, created, lastMembershipUpdated, lastUpdated, and type. * The source of groups with type of APP_GROUP, accessed as source.id. You can also use sortBy and sortOrder parameters.

Examples:
search=type eq "APP_GROUP"
search=lastMembershipUpdated gt "2014-01-01T00:00:00.000Z"
search=id eq "00gak46y5hydV6NdM0g4"
search=profile.name eq "West Coast users"
search=profile.samAccountName sw "West Coast"
search=source.id eq "0oa2v0el0gP90aqjJ0g7"
search=type eq "APP_GROUP" and (created lt "2014-01-01T00:00:00.000Z" and source.id eq "0oa2v0el0gP90aqjJ0g7")
sortBy
string

Specifies field to sort by (for search queries only). sortBy can be any single property, for example sortBy=profile.name.

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

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

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/groups
Request samples
Response samples
application/json

Lists an example of an OKTA_GROUP and an APP_GROUP

[]

Add a group
OAuth 2.0: okta.groups.manage

Adds a new group with the OKTA_GROUP type to your org

Note: App import operations are responsible for syncing groups with APP_GROUP type such as Active Directory groups. See About groups.

Request
Request Body schema: application/json
required
object (OktaUserGroupProfile)

Profile for any group that is not imported from Active Directory. Specifies the standard and custom profile properties for a group.

The objectClass for these groups is okta:user_group.

description
string

Description of the group

name
string

Name of the group

Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/groups
Request samples
application/json
{
  • "profile": {
    • "description": "All users West of The Rockies",
    • "name": "West Coast users"
    }
}
Response samples
application/json

Example of a group

{}

Retrieve a group
OAuth 2.0: okta.groups.read

Retrieves a specific group by id from your org

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

Example of a group

{}

Replace a group
OAuth 2.0: okta.groups.manage

Replaces the profile for a group of OKTA_GROUP type from your org

Note : You only can modify profiles for groups of the OKTA_GROUP type.

App imports are responsible for updating profiles for groups of the APP_GROUP type, such as Active Directory groups.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
Request Body schema: application/json
required
object (OktaUserGroupProfile)

Profile for any group that is not imported from Active Directory. Specifies the standard and custom profile properties for a group.

The objectClass for these groups is okta:user_group.

description
string

Description of the group

name
string

Name of the 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": "All users West of The Rockies",
    • "name": "West Coast users"
    }
}
Response samples
application/json

Example of a group

{}

Delete a group
OAuth 2.0: okta.groups.manage

Deletes a group of the OKTA_GROUP or APP_GROUP type from your org

Note: You can't remove groups of type APP_GROUP if they are used in a group push mapping.

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 apps that are assigned to a group. See Application Groups API.

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

List all apps example

[]

List all member users
OAuth 2.0: okta.groups.read

Lists all users that are a member of a group.

The default user limit is set to a very high number due to historical reasons that are no longer valid for most orgs. This will change in a future version of this API. The recommended page limit is now limit=200.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
query Parameters
after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.

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
[
  • {
    • "id": "00u118oQYT4TBTemp0g4",
    • "status": "ACTIVE",
    • "created": "2022-04-04T15:56:05.000Z",
    • "activated": null,
    • "statusChanged": null,
    • "lastLogin": "2022-05-04T19:50:52.000Z",
    • "lastUpdated": "2022-05-05T18:15:44.000Z",
    • "passwordChanged": "2022-04-04T16:00:22.000Z",
    • "type": {
      },
    • "profile": {
      },
    • "credentials": {
      },
    }
]

Assign a user to a group
OAuth 2.0: okta.groups.manage

Assigns a user to a group with the OKTA_GROUP type

Note: You only can modify memberships for groups of the OKTA_GROUP type. App imports are responsible for managing group memberships for groups of the APP_GROUP type, such as Active Directory groups.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
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 from a group
OAuth 2.0: okta.groups.manage

Unassigns a user from a group with the OKTA_GROUP type

Note: You only can modify memberships for groups of the OKTA_GROUP type.

App imports are responsible for managing group memberships for groups of the APP_GROUP type, such as Active Directory groups.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
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": [ ]
}