Role Assignment

The Role Assignment API provides operations to assign, unassign, or list the roles for a client.

List all Roles for a Client
OAuth 2.0: okta.roles.read

Lists all Roles by clientId

Request
path Parameters
clientId
required
string

client_id of the Client application

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/oauth2/v1/clients/{clientId}/roles
Request samples
Response samples
application/json
[]

Assign Role to Client
OAuth 2.0: okta.roles.manage

Assigns a Role to a Client

Request
path Parameters
clientId
required
string

client_id of the Client application

Request Body schema: application/json
required
One of:
type
string

Standard role type

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/oauth2/v1/clients/{clientId}/roles
Request samples
application/json
{
  • "type": "HELP_DESK_ADMIN,"
}
Response samples
application/json
{}

Retrieve a Client Role
OAuth 2.0: okta.roles.read

Retrieves a Client Role

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/oauth2/v1/clients/{clientId}/roles/{roleId}
Request samples
Response samples
application/json
{}

Unassign a Role from a Client
OAuth 2.0: okta.roles.manage

Unassigns a Role from a Client

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/oauth2/v1/clients/{clientId}/roles/{roleId}
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 App Targets
OAuth 2.0: okta.roles.read

Lists App Targets for Client and Role

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

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 for more information.

Note: The after cursor should be treated as an opaque value and obtained through the next link relation.

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 Application Target
OAuth 2.0: okta.roles.manage

Assigns an Application Target to a Client

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

appName
required
string

name of the application

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 Application Target
OAuth 2.0: okta.roles.manage

Removes an Application Target by clientId

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

appName
required
string

name of the application

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 Target
OAuth 2.0: okta.roles.manage

Replaces an App Instance Target by clientId

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

appName
required
string

name of the application

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
OAuth 2.0: okta.roles.manage

Deletes an App Instance Target from a Client

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

appName
required
string

name of the application

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
OAuth 2.0: okta.roles.read

Lists all Group Targets by clientId and roleId

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

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 for more information.

Note: The after cursor should be treated as an opaque value and obtained through the next link relation.

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
[]

Replace a Group Target
OAuth 2.0: okta.roles.manage

Replaces a Group Target on a Client

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

groupId
required
string

id of the group

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
OAuth 2.0: okta.roles.manage

Deletes a Group Target from a Client

Request
path Parameters
clientId
required
string

client_id of the Client application

roleId
required
string

role_id of the role

groupId
required
string

id of the group

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