User Role Targets

User role targets are a way of limiting the app or group resources for a standard role that's assigned to an admin user within your org. You can define admin roles to target groups, apps, and app 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. For custom roles, use Resource Sets to define specific targets. See the Role Assignments concept.

List all admin role app targets
OAuth 2.0: okta.roles.read

Lists all app targets for an APP_ADMIN role assigned to a user. The response is a list that includes OIN-cataloged apps or app instances. The response payload for an app instance contains the id property, but an OIN-cataloged app payload doesn't.

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
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 [ 1 .. 200 ]
Default: 20

A limit on the number of objects to return

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/roles/{roleAssignmentId}/targets/catalog/apps
Request samples 
Response samples 
application/json
[
  • {
    • "category": "SOCIAL",
    • "description": "string",
    • "displayName": "string",
    • "features": [
      ],
    • "id": "string",
    • "lastUpdated": "2024-09-19T23:37:37.000Z",
    • "name": "string",
    • "signOnModes": [
      ],
    • "status": "ACTIVE",
    • "verificationStatus": "OKTA_VERIFIED",
    • "website": "string",
    • "_links": {
      }
    }
]
Assign all apps as target to admin role
OAuth 2.0: okta.roles.manage
Assigns all apps as target to an APP_ADMIN role


Request 
path Parameters
userId
required
string
ID of an existing Okta user


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


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/users/{userId}/roles/{roleAssignmentId}/targets/catalog/apps
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 admin role app target
OAuth 2.0: okta.roles.manage
Assigns an OIN app target for an APP_ADMIN role assignment to an admin user. When you assign the first 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.


Assigning an OIN app target overrides any existing app instance targets of the OIN app.
For example, if a user was assigned to administer a specific Facebook instance, a successful request to add an OIN app target with facebook for appName makes that user the administrator for all Facebook instances.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


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


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
appName
required
string
Name of the app definition (the OIN catalog app key name)


 
 Example:  google
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/users/{userId}/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 an admin role app target
OAuth 2.0: okta.roles.manage
Unassigns an OIN app target from an APP_ADMIN role assignment to an admin user.




Note: You can't remove the last OIN 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 to the user and recreate a new one.




Request 
path Parameters
userId
required
string
ID of an existing Okta user


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


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
appName
required
string
Name of the app definition (the OIN catalog app key name)


 
 Example:  google
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{userId}/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 admin role app instance target
OAuth 2.0: okta.roles.manage
Assigns an app instance target to an APP_ADMIN role assignment to an admin user. 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 can't assign permissions to manage all instances of an OIN app and then assign a subset of permission to the same OIN 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
userId
required
string
ID of an existing Okta user


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


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
appName
required
string
Name of the app definition (the OIN catalog app key name)


 
 Example:  google
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/users/{userId}/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 admin role app instance target
OAuth 2.0: okta.roles.manage
Unassigns an app instance target from an APP_ADMIN role assignment to an admin user.




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.




Request 
path Parameters
userId
required
string
ID of an existing Okta user


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


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
appName
required
string
Name of the app definition (the OIN catalog app key name)


 
 Example:  google
appId
required
string
Application ID


 
 Example:  0oafxqCAJWWGELFTYASJ
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{userId}/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 admin 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 an admin user.
If the role isn't scoped to specific group targets, an empty array [] is returned.


Request 
path Parameters
userId
required
string
ID of an existing Okta user


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


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
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  [ 1 .. 200 ] 
 Default:  20
A limit on the number of objects to return


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/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 an admin role group target
OAuth 2.0: okta.roles.manage
Assigns a group target for a USER_ADMIN, HELP_DESK_ADMIN, or GROUP_MEMBERSHIP_ADMIN role assignment to an admin user.
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
userId
required
string
ID of an existing Okta user


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


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/users/{userId}/roles/{roleAssignmentId}/targets/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": [ ]
}
Unassign an admin 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 an admin user.




Note: You can't remove the last group target from a role assignment since this causes an exception.
If you need a role assignment that applies to all groups, delete the role assignment to the user and recreate a new one.




Request 
path Parameters
userId
required
string
ID of an existing Okta user


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


 
 Example:  JBCUYUC7IRCVGS27IFCE2SKO
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/users/{userId}/roles/{roleAssignmentId}/targets/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": [ ]
}