Role Targets

Role targets are a way of defining permissions for admin roles into a smaller subset of Groups or Apps within your org. Targets limit an admin's permissions to a targeted area of the 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 the specified Apps. Target Apps are Okta catalog Apps. For example, you can have multiple configurations of an Okta catalog App, such as Salesforce or Facebook. When you add a Salesforce or Facebook App as a target, that grants the admin permission to manage all the instances of those Apps and create new instances of them.
  • App Instance targets: Grant an admin permission to manage an instance of one App or instances of multiple Apps. App Instances are specific Apps that admins have created in their org. For example, there may be a Salesforce App configured differently for each sales region of a company. When you create an App Instance target, you can assign an admin to manage only two instances of the configured Salesforce Apps and then also to manage an instance of another configured App such as Workday.

Note: Don't use these operations with a Custom Role ID. Custom Role assignments always require a target Resource Set. See Role Assignments for more information.

List all Application Targets for an Application Administrator Role
OAuth 2.0: okta.roles.read

Lists all App targets for an APP_ADMIN Role assigned to a Group. This methods return list may include full Applications or Instances. The response for an instance will have an ID value, while Application will not have an ID.

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
roleId
required
string

id of the Role

Example: 3Vg1Pjp3qzw4qcCK5EdO
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/{roleId}/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 Application Target to Administrator Role
OAuth 2.0: okta.roles.manage
Assigns an application target to administrator role


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/{roleId}/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 Application Target from Application Administrator Role
OAuth 2.0: okta.roles.manage
Unassigns an application target from application administrator role


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/{roleId}/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 Application Instance Target to Application Administrator Role
OAuth 2.0: okta.roles.manage
Assigns App Instance Target to App Administrator Role given to a Group


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/{roleId}/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 Application Instance Target from an Application Administrator Role
OAuth 2.0: okta.roles.manage
Unassigns an application instance target from application administrator role


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/{roleId}/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 Targets for a Group Role
OAuth 2.0: okta.roles.read
Lists all group targets for a group role


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/{roleId}/targets/groups
Request samples 
Response samples 
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "lastMembershipUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "objectClass": [
      ],
    • "profile": {
      },
    • "type": "APP_GROUP",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
Assign a Group Target to a Group Role
OAuth 2.0: okta.roles.manage
Assigns a group target to a group role


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
targetGroupId
required
string
 
 Example:  00g1e9dfjHeLAsdX983d
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/groups/{groupId}/roles/{roleId}/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 Target from a Group Role
OAuth 2.0: okta.roles.manage
Unassigns a group target from a group role


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
targetGroupId
required
string
 
 Example:  00g1e9dfjHeLAsdX983d
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/groups/{groupId}/roles/{roleId}/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": [ ]
}
List all Application Targets for Application Administrator Role
OAuth 2.0: okta.roles.read
Lists all App targets for an APP_ADMIN Role assigned to a User. This methods return list may include full Applications or Instances. The response for an instance will have an ID value, while Application will not have an ID.


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
query Parameters
after
string
 
limit
integer <int32> 
 Default:  20
 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/roles/{roleId}/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 all Apps as Target to Role
OAuth 2.0: okta.roles.manage
Assigns all Apps as Target to Role


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/users/{userId}/roles/{roleId}/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 Application Target to Administrator Role
OAuth 2.0: okta.roles.manage
Assigns an application target to administrator role


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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


put/api/v1/users/{userId}/roles/{roleId}/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 Application Target from an Application Administrator Role
OAuth 2.0: okta.roles.manage
Unassigns an application target from application administrator role


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/users/{userId}/roles/{roleId}/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 Application Instance Target to an Application Administrator Role
OAuth 2.0: okta.roles.manage
Assigns anapplication instance target to appplication administrator role


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/users/{userId}/roles/{roleId}/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 Application Instance Target from an Application Administrator Role
OAuth 2.0: okta.roles.manage
Unassigns an application instance target from an application administrator role


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/users/{userId}/roles/{roleId}/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 Targets for Role
OAuth 2.0: okta.roles.read
Lists all group targets for role


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
query Parameters
after
string
 
limit
integer <int32> 
 Default:  20
 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/roles/{roleId}/targets/groups
Request samples 
Response samples 
application/json
[
  • {
    • "created": "2019-08-24T14:15:22Z",
    • "id": "string",
    • "lastMembershipUpdated": "2019-08-24T14:15:22Z",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "objectClass": [
      ],
    • "profile": {
      },
    • "type": "APP_GROUP",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
Assign a Group Target to Role
OAuth 2.0: okta.roles.manage
Assigns a Group Target to Role


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/{roleId}/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 a Group Target from Role
OAuth 2.0: okta.roles.manage
Unassigns a Group Target from Role


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


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
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/{roleId}/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": [ ]
}