Group Role Targets

Group role targets allow you to limit the app or group resources for a standard role that's assigned to a group within your org. You can define admin roles to target groups, Applications, and Application Instances.

  • Group targets: Grant an admin permission to manage only a specified group. For example, an admin role may be assigned to manage only the IT group.
  • App targets: Grant an admin permission to manage all instances of an OIN-cataloged app integration. For example, an admin role can manage all customer instances of an OIN-cataloged app, such as Salesforce or Facebook.
  • App instance targets: Grant an admin permission to manage an instance of an OIN-catalog app. For example, there may be a few Salesforce app instances configured for each sales region of an org. You can configure an admin to manage two Salesforce instances in a specific region and not the other regional Salesforce instances.

Note: You can only use the User Role Targets API with standard roles. You can define specific targets for custom roles with Resource Set Resources. See the Role Assignments concept.

List all Group Role Application Targets
OAuth 2.0: okta.roles.read

Lists all app targets for an APP_ADMIN Role Assignment to a Group. The response includes a list of OIN-cataloged apps or app instances. The response payload for an app instance contains the id property, but an OIN-cataloged app doesn't.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
query Parameters
after
string
limit
integer <int32>
Default: 20
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/groups/{groupId}/roles/{roleAssignmentId}/targets/catalog/apps
Request samples
Response samples
application/json
[
  • {
    • "category": "string",
    • "description": "string",
    • "displayName": "string",
    • "features": [
      ],
    • "id": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "name": "string",
    • "signOnModes": [
      ],
    • "status": "ACTIVE",
    • "verificationStatus": "string",
    • "website": "string",
    • "_links": {
      }
    }
]

Assign an Group Role Application Target
OAuth 2.0: okta.roles.manage

Assigns an OIN app target to an APP_ADMIN Role Assignment to a Group. When you assign the first OIN app target, you reduce the scope of the Role Assignment. The Role no longer applies to all app targets but applies only to the specified target. An OIN app target that's assigned to the Role overrides any existing instance targets of the OIN app. For example, if a user is assigned to administer a specific Facebook instance, a successful request to add an OIN app with facebook for appName makes that user the administrator for all Facebook instances.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
appName
required
string

Application name for the app type

Example: oidc_client
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/groups/{groupId}/roles/{roleAssignmentId}/targets/catalog/apps/{appName}
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 Group Role Application Target
OAuth 2.0: okta.roles.manage

Unassigns an OIN app target from an APP_ADMIN Role Assignment to a Group

Note: You can't remove the last app target from a Role Assignment, since this causes an exception. If you need a Role Assignment that applies to all apps, delete the APP_ADMIN Role Assignment and recreate a new one. See Unassign a Group Role.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
appName
required
string

Application name for the app type

Example: oidc_client
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

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

Assign an Group Role Application Instance Target
OAuth 2.0: okta.roles.manage

Assigns an app instance target to an APP_ADMIN Role Assignment to a Group. When you assign the first OIN app or app instance target, you reduce the scope of the Role Assignment. The Role no longer applies to all app targets, but applies only to the specified target.

Note: You can target a mixture of both OIN app and app instance targets, but you can't assign permissions to manage all instances of an OIN app and then assign a subset of permissions to the same app. For example, you can't specify that an admin has access to manage all instances of the Salesforce app and then also manage specific configurations of the Salesforce app.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
appName
required
string

Application name for the app type

Example: oidc_client
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/groups/{groupId}/roles/{roleAssignmentId}/targets/catalog/apps/{appName}/{appId}
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 an Group Role Application Instance Target
OAuth 2.0: okta.roles.manage

Unassigns an app instance target from an APP_ADMIN Role Assignment to a Group

Note: You can't remove the last app instance target from a Role Assignment since this causes an exception. > If you need a Role Assignment that applies to all apps, delete the APP_ADMIN Role Assignment and recreate a new one. See Unassign a Group Role.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
appName
required
string

Application name for the app type

Example: oidc_client
appId
required
string

Application ID

Example: 0oafxqCAJWWGELFTYASJ
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/groups/{groupId}/roles/{roleAssignmentId}/targets/catalog/apps/{appName}/{appId}
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 Group Role Group Targets
OAuth 2.0: okta.roles.read

Lists all Group targets for a USER_ADMIN, HELP_DESK_ADMIN, or GROUP_MEMBERSHIP_ADMIN Role Assignment to a Group. If the Role isn't scoped to specific Group targets, an empty array [] is returned.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
query Parameters
after
string
limit
integer <int32>
Default: 20
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

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

Assign a Group Role Group Target
OAuth 2.0: okta.roles.manage

Assigns a Group target to a USER_ADMIN, HELP_DESK_ADMIN, or GROUP_MEMBERSHIP_ADMIN Role Assignment to a Group. When you assign the first Group target, you reduce the scope of the Role Assignment. The Role no longer applies to all targets but applies only to the specified target.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
targetGroupId
required
string
Example: 00g1e9dfjHeLAsdX983d
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/groups/{groupId}/roles/{roleAssignmentId}/targets/groups/{targetGroupId}
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 Group Role Group Target
OAuth 2.0: okta.roles.manage

Unassigns a Group target from a USER_ADMIN, HELP_DESK_ADMIN, or GROUP_MEMBERSHIP_ADMIN Role Assignment to a Group.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
targetGroupId
required
string
Example: 00g1e9dfjHeLAsdX983d
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

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