Custom Role Permissions

The Custom Role Permissions API provides operations to manage the permissions assigned to a custom role.

List all custom role permissions
OAuth 2.0 scopes:
  • okta.roles.read

Lists all permissions for a custom role by roleIdOrLabel

Request
path Parameters
roleIdOrLabel
required
string

id or label of the role

Example: cr0Yq6IJxGIr0ouum0g3
Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/iam/roles/{roleIdOrLabel}/permissions
Request samples 
Response samples 
application/json
{}
Retrieve a custom role permission
OAuth 2.0 scopes: 
  • okta.roles.read
Retrieves a permission (identified by permissionType) for a custom role


Request 
path Parameters
roleIdOrLabel
required
string
id or label of the role


 
 Example:  cr0Yq6IJxGIr0ouum0g3
permissionType
required
string
An Okta permission


 
 Example:  okta.users.manage
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/iam/roles/{roleIdOrLabel}/permissions/{permissionType}
Request samples 
Response samples 
application/json
{}
Create a custom role permission
OAuth 2.0 scopes: 
  • okta.roles.manage
Creates a permission (specified by permissionType) for a custom role


Request 
path Parameters
roleIdOrLabel
required
string
id or label of the role


 
 Example:  cr0Yq6IJxGIr0ouum0g3
permissionType
required
string
An Okta permission


 
 Example:  okta.users.manage
Request Body schema: application/json
optional
object or null (PermissionConditions) 
Conditions for further restricting a permission. See Permission conditions.


 
object or null
Exclude attributes with specific values for the permission


 
property name*
additional property
object
 
object or null
Include attributes with specific values for the permission


 
property name*
additional property
object
 
Responses 
204
No Content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/iam/roles/{roleIdOrLabel}/permissions/{permissionType}
Request samples 
application/json
{
  • "conditions": {
    • "include": {
      }
    }
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Replace a custom role permission
OAuth 2.0 scopes: 
  • okta.roles.manage
Replaces a permission (specified by permissionType) for a custom role


Request 
path Parameters
roleIdOrLabel
required
string
id or label of the role


 
 Example:  cr0Yq6IJxGIr0ouum0g3
permissionType
required
string
An Okta permission


 
 Example:  okta.users.manage
Request Body schema: application/json
optional
object or null (PermissionConditions) 
Conditions for further restricting a permission. See Permission conditions.


 
object or null
Exclude attributes with specific values for the permission


 
property name*
additional property
object
 
object or null
Include attributes with specific values for the permission


 
property name*
additional property
object
 
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/iam/roles/{roleIdOrLabel}/permissions/{permissionType}
Request samples 
application/json
{
  • "conditions": {
    • "include": {
      }
    }
}
Response samples 
application/json
{}
Delete a custom role permission
OAuth 2.0 scopes: 
  • okta.roles.manage
Deletes a permission (identified by permissionType) from a custom role


Request 
path Parameters
roleIdOrLabel
required
string
id or label of the role


 
 Example:  cr0Yq6IJxGIr0ouum0g3
permissionType
required
string
An Okta permission


 
 Example:  okta.users.manage
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/iam/roles/{roleIdOrLabel}/permissions/{permissionType}
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": [ ]
}