Roles

The Roles API provides operations to manage administrative Role assignments for a User.

Role listing APIs provide a union of both standard and Custom Roles assigned to a User or Group.

List all Roles
OAuth 2.0: okta.roles.read

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

Responses
200

OK

403

Forbidden

429

Too Many Requests

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


Request 
Request Body schema: application/json
required
description
required
string
Description of the role


 
label
required
string
Unique label for the role


 
permissions
required
Array of strings (RolePermissionType) 
Array of permissions that the role will grant. See Permission Types.


Items Enum: "okta.apps.assignment.manage" "okta.apps.manage" "okta.apps.manageFirstPartyApps" "okta.apps.read" "okta.authzServers.manage" "okta.authzServers.read" "okta.customizations.manage" "okta.customizations.read" "okta.devices.lifecycle.activate" "okta.devices.lifecycle.deactivate" "okta.devices.lifecycle.delete" "okta.devices.lifecycle.manage" "okta.devices.lifecycle.suspend" "okta.devices.lifecycle.unsuspend" "okta.devices.manage" "okta.devices.read" "okta.governance.accessCertifications.manage" "okta.governance.accessRequests.manage" "okta.groups.appAssignment.manage" "okta.groups.create" "okta.groups.manage" "okta.groups.members.manage" "okta.groups.read" "okta.identityProviders.manage" "okta.identityProviders.read" "okta.profilesources.import.run" "okta.users.appAssignment.manage" "okta.users.create" "okta.users.credentials.expirePassword" "okta.users.credentials.manage" "okta.users.credentials.resetFactors" "okta.users.credentials.resetPassword" "okta.users.groupMembership.manage" "okta.users.lifecycle.activate" "okta.users.lifecycle.clearSessions" "okta.users.lifecycle.deactivate" "okta.users.lifecycle.delete" "okta.users.lifecycle.manage" "okta.users.lifecycle.suspend" "okta.users.lifecycle.unlock" "okta.users.lifecycle.unsuspend" "okta.users.manage" "okta.users.read" "okta.users.userprofile.manage"  
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: 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 Role
OAuth 2.0: okta.roles.manage
Replaces a role by roleIdOrLabel


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


 
 Example:  cr0Yq6IJxGIr0ouum0g3
Request Body schema: application/json
required
description
required
string
Description of the role


 
label
required
string
Unique label for 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",
  • "permissions": [
    • "okta.users.create",
    • "okta.users.read",
    • "okta.groups.read",
    • "okta.users.userprofile.manage"
    ]
}
Response samples 
application/json
{}
Delete a Role
OAuth 2.0: okta.roles.manage
Deletes a 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": [ ]
}
List all Permissions
OAuth 2.0: okta.roles.read
Lists all permissions of the 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 Permission
OAuth 2.0: okta.roles.read
Retrieves a permission by permissionType


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


 
 Example:  cr0Yq6IJxGIr0ouum0g3
permissionType
required
string
An okta permission type


 
 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 Permission
OAuth 2.0: okta.roles.manage
Creates a permission specified by permissionType to the role


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


 
 Example:  cr0Yq6IJxGIr0ouum0g3
permissionType
required
string
An okta permission type


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


 
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 Permission
OAuth 2.0: okta.roles.manage
Replaces a permission specified by permissionType in the role


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


 
 Example:  cr0Yq6IJxGIr0ouum0g3
permissionType
required
string
An okta permission type


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


 
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 Permission
OAuth 2.0: okta.roles.manage
Deletes a permission from a role by permissionType


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


 
 Example:  cr0Yq6IJxGIr0ouum0g3
permissionType
required
string
An okta permission type


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