Application Groups

The Application Groups API provides a set of operations to manage group assignment for an app.

List all Application Groups
OAuth 2.0: okta.apps.read

Lists all app group assignments

Request
path Parameters
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
query Parameters
q
string

Specifies a filter for a list of assigned groups returned based on their names. The value of q is matched against the group name. This filter only supports the startsWith operation that matches the q string against the beginning of the Group name.

Example: q=test
after
string

Specifies the pagination cursor for the next page of results. Treat this as an opaque value obtained through the next link relationship. See Pagination.

Example: after=16275000448691
limit
integer <int32> [ 20 .. 200 ]
Default: 20

Specifies the number of objects to return per page. If there are multiple pages of results, the Link header contains a next link that you need to use as an opaque value (follow it, don't parse it). See Pagination.

Examples:
limit=20
limit=100
limit=200
expand
string

An optional query parameter to return the corresponding assigned Group or the group assignment metadata details in the _embedded property.

Examples:
expand=group
expand=metadata
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/apps/{appId}/groups
Request samples 
Response samples 
application/json
[]
Retrieve an Application Group
OAuth 2.0: okta.apps.read
Retrieves an app group assignment


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
query Parameters
expand
string
An optional query parameter to return the corresponding assigned Group or 
the group assignment metadata details in the _embedded property.


  Examples: 
expand=group
expand=metadata
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/apps/{appId}/groups/{groupId}
Request samples 
Response samples 
application/json
{}
Assign an Application Group
OAuth 2.0: okta.apps.manage
Assigns a Group to an app, which in turn assigns the app to each User that belongs to the group. 
The resulting Application User scope is GROUP since the assignment was from the group membership.


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
Request Body schema: application/json
optional
priority
integer
Priority assigned to the group. If an app has more than one group assigned to the same user, then the group with the higher priority has its profile applied to the Application User.
If a priority value isn't specified, then the next highest priority is assigned by default.
See Assign attribute group priority and the sample priority use case.


 
object (GroupAssignmentProfile) 
Specifies the profile properties applied to Application Users that are assigned to the app through group membership. 
Some reference properties are imported from the target app and can't be configured. See profile.


 
property name*
additional property
any
 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/apps/{appId}/groups/{groupId}
Request samples 
application/json
{
  • "id": "00g15acRUy0SYb9GT0g4",
  • "profile": {
    • "preferredLanguage": "English",
    • "manager": "Arsene Wenger",
    • "securityQuestion": "Who is the footballer to have played the game",
    • "securityAnswer": "Jay Jay Okocha",
    • "timezone": "Canada/Eastern",
    • "initialStatus": "active_with_pass",
    • "managerId": "ike.ogb@gmail.com",
    • "locale": "en_US",
    • "division": "top",
    • "organization": null,
    • "userType": null,
    • "department": "Accounting"
    }
}
Response samples 
application/json
{}
Update an Application Group
OAuth 2.0: okta.apps.manage
Updates a group assignment to an app


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
Request Body schema: application/json
optional
 Array 
op
string (PatchAction) 
The operation (PATCH action)


 Enum: Description
remove
Removes the attribute in path


replace
Replaces the attribute in content path with the content in value


 
path
string
The resource path of the attribute to update


 
value
object
The update operation value


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


patch/api/v1/apps/{appId}/groups/{groupId}
Request samples 
application/json
[
  • {
    • "op": "replace",
    • "path": "/profile/manager",
    • "value": "Carlo Ancelotti"
    }
]
Response samples 
application/json
{}
Unassign an Application Group
OAuth 2.0: okta.apps.manage
Unassigns a Group from an app


Request 
path Parameters
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
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/apps/{appId}/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": [ ]
}