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: 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: 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 strings (RolePermissionType)

Array of permissions that the Role grants. See Permissions.

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.support.cases.manage" "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 Custom Role
OAuth 2.0: 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: 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": [ ]
}