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.

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