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": {
      },
    • "_links": {}
    }
]
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": [ ]
}