Custom Roles

The Custom Roles API provides operations to manage custom roles that limit an admin's access to a subset of permissions and resources.

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

Lists all custom roles with pagination support

Request
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.

Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/iam/roles
Request samples 
Response samples 
application/json
{}
Create a custom role
OAuth 2.0 scopes: 
  • okta.roles.manage
Creates a custom role


Request 
Request Body schema: application/json
required
label
required
string
Unique label for the role


 
description
required
string
Description of the role


 
permissions
required
Array of arrays
Array of permissions that the role grants. See Permissions.


 
Responses 
200
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/iam/roles
Request samples 
application/json
{
  • "label": "UserCreator",
  • "description": "Create users",
  • "permissions": [
    • "okta.users.create",
    • "okta.users.read",
    • "okta.groups.read",
    • "okta.users.userprofile.manage"
    ]
}
Response samples 
application/json
{}
Retrieve a role
OAuth 2.0 scopes: 
  • okta.roles.read
Retrieves a 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}
Request samples 
Response samples 
application/json
{}
Replace a custom role
OAuth 2.0 scopes: 
  • okta.roles.manage
Replaces the label and description for a custom role by roleIdOrLabel


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


 
 Example:  cr0Yq6IJxGIr0ouum0g3
Request Body schema: application/json
required
label
required
string
Unique label for the role


 
description
required
string
Description of the role


 
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/iam/roles/{roleIdOrLabel}
Request samples 
application/json
{
  • "label": "UserCreator",
  • "description": "Create users"
}
Response samples 
application/json
{}
Delete a custom role
OAuth 2.0 scopes: 
  • okta.roles.manage
Deletes a custom role by roleIdOrLabel


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


 
 Example:  cr0Yq6IJxGIr0ouum0g3
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


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