Group Role Assignments

The Group Role Assignments APIs allow you to assign roles and designate third-party admin status to groups.

List all group role assignments
OAuth 2.0: okta.roles.read

Lists all assigned roles of a group by groupId

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
query Parameters
expand
string

An optional parameter used to return targets configured for the standard Role Assignment in the embedded property. Supported values: targets/groups or targets/catalog/apps

Examples:
expand=targets/groups
expand=targets/catalog/apps
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/groups/{groupId}/roles
Request samples 
Response samples 
application/json
[
  • {
    • "id": "IFIFAX2BIRGUSTQ",
    • "label": "Application Administrator",
    • "type": "APP_ADMIN",
    • "status": "ACTIVE",
    • "created": "2019-02-06T16:17:40.000Z",
    • "lastUpdated": "2019-02-06T16:17:40.000Z",
    • "assignmentType": "GROUP",
    • "_links": {}
    }
]
Assign a role to a group
OAuth 2.0: okta.roles.manage
Assigns a standard role to a group.


You can also assign a custom role to a group, but the preferred method to assign a custom role to a group is to create a binding between the custom role, the resource set, and the group. See Create a role resource set binding.




Notes:


    

  • The request payload is different for standard and custom role assignments.
    • 

  • For IAM-based standard role assignments, use the request payload for standard roles. However, the response payload for IAM-based role assignments is similar to the custom role's assignment response.
    • 





Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
query Parameters
disableNotifications
boolean
 Default:  false
Grants the Group third-party admin status when set to true


 
Request Body schema: application/json
required
One of:
type
string
Specify the standard or IAM-based role type. See standard roles.


 
Responses 
200
Success


201
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/groups/{groupId}/roles
Request samples 
application/json
{
  • "type": "string"
}
Response samples 
application/json
{
  • "id": "grasraHPx7i79ajaJ0g3",
  • "label": "Organization Administrator",
  • "type": "ORG_ADMIN",
  • "status": "ACTIVE",
  • "created": "2019-02-27T14:56:55.000Z",
  • "lastUpdated": "2019-02-27T14:56:55.000Z",
  • "assignmentType": "GROUP",
  • "_links": {}
}
Retrieve a group role assignment
OAuth 2.0: okta.roles.read
Retrieves a role assigned to a group (identified by the groupId). The roleAssignmentId is the unique identifier for either a standard role group assignment object or a custom role resource set binding object.


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string
The id of the role assignment


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/groups/{groupId}/roles/{roleAssignmentId}
Request samples 
Response samples 
application/json
{
  • "id": "grasraHPx7i79ajaJ0g3",
  • "label": "Organization Administrator",
  • "type": "ORG_ADMIN",
  • "status": "ACTIVE",
  • "created": "2019-02-27T14:56:55.000Z",
  • "lastUpdated": "2019-02-27T14:56:55.000Z",
  • "assignmentType": "GROUP",
  • "_links": {}
}
Unassign a group role
OAuth 2.0: okta.roles.manage
Unassigns a role assignment (identified by roleAssignmentId) from a group (identified by the groupId)


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string
The id of the role assignment


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/groups/{groupId}/roles/{roleAssignmentId}
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": [ ]
}