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": [ ]
}

List all App Targets assigned to a Client
OAuth 2.0: okta.roles.read

Lists App Targets for Client and Role

Request
path Parameters
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
roleId
required
string

id of the Role

Example: 3Vg1Pjp3qzw4qcCK5EdO
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/oauth2/v1/clients/{clientId}/roles/{roleId}/targets/catalog/apps
Request samples
Response samples
application/json
[
  • {
    • "name": "google",
    • "displayName": "Google Workspace",
    • "description": "Gmail, Google Drive, Google Calendar, and Google Sites",
    • "status": "ACTIVE",
    • "lastUpdated": "2021-06-23T22:23:29.000Z",
    • "category": "COLLABORATION",
    • "verificationStatus": "OKTA_VERIFIED",
    • "signOnModes": [
      ],
    • "features": [
      ],
    • "_links": {}
    }
]

Assign an App Target to a Client
OAuth 2.0: okta.roles.manage

Assigns an Application Target to a Client

Request
path Parameters
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
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/oauth2/v1/clients/{clientId}/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": [ ]
}

Remove an App Target from a Client
OAuth 2.0: okta.roles.manage

Removes an Application Target by clientId

Request
path Parameters
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
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/oauth2/v1/clients/{clientId}/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": [ ]
}

Replace an App Instance Target for a Client
OAuth 2.0: okta.roles.manage

Replaces an App Instance Target by clientId

Request
path Parameters
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
roleId
required
string

id of the Role

Example: 3Vg1Pjp3qzw4qcCK5EdO
appName
required
string

Application name for the app type

Example: oidc_client
appInstanceId
required
string

id of the application instance

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

put/oauth2/v1/clients/{clientId}/roles/{roleId}/targets/catalog/apps/{appName}/{appInstanceId}
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": [ ]
}

Delete an App Instance Target for a Client
OAuth 2.0: okta.roles.manage

Deletes an App Instance Target from a Client

Request
path Parameters
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
roleId
required
string

id of the Role

Example: 3Vg1Pjp3qzw4qcCK5EdO
appName
required
string

Application name for the app type

Example: oidc_client
appInstanceId
required
string

id of the application instance

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/oauth2/v1/clients/{clientId}/roles/{roleId}/targets/catalog/apps/{appName}/{appInstanceId}
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 Client
OAuth 2.0: okta.roles.read

Lists all Group Targets by clientId and roleId

Request
path Parameters
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
roleId
required
string

id of the Role

Example: 3Vg1Pjp3qzw4qcCK5EdO
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/oauth2/v1/clients/{clientId}/roles/{roleId}/targets/groups
Request samples
Response samples
application/json
[]

Assign a Group Target to a Client
OAuth 2.0: okta.roles.manage

Assigns a Group Target to a Client

Request
path Parameters
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
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/oauth2/v1/clients/{clientId}/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": [ ]
}

Delete a Group Target from a Client
OAuth 2.0: okta.roles.manage

Deletes a Group Target from a Client

Request
path Parameters
clientId
required
string

client_id of the app

Example: 52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
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/oauth2/v1/clients/{clientId}/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": [ ]
}