User Role Assignments

The User Role Assignments APIs allow you to assign roles and designate third-party admin status to Users.

List all Users with Role Assignments
OAuth 2.0: okta.roles.read

Lists all users with Role Assignments

Request
query Parameters
after
string

Specifies the pagination cursor for the next page of targets

limit
integer <int32>
Default: 100

Specifies the number of results returned. Defaults to 100.

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/iam/assignees/users
Request samples
Response samples
application/json
{}

List all user role assignments
OAuth 2.0: okta.roles.read

Lists all roles assigned to a user (identified by userId)

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
query Parameters
expand
string

An optional parameter used to return targets configured for the standard Role Assignment in the embedded property. Supported values: targets/groups or targets/catalog/apps

Examples:
expand=targets/groups
expand=targets/catalog/apps
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/roles
Request samples
Response samples
application/json
[
  • {
    • "id": "IFIFAX2BIRGUSTQ",
    • "label": "Application administrator",
    • "type": "APP_ADMIN",
    • "status": "ACTIVE",
    • "created": "2019-02-06T16:17:40.000Z",
    • "lastUpdated": "2019-02-06T16:17:40.000Z",
    • "assignmentType": "USER",
    },
  • {
    • "id": "JBCUYUC7IRCVGS27IFCE2SKO",
    • "label": "Help Desk administrator",
    • "type": "HELP_DESK_ADMIN",
    • "status": "ACTIVE",
    • "created": "2019-02-06T16:17:40.000Z",
    • "lastUpdated": "2019-02-06T16:17:40.000Z",
    • "assignmentType": "USER",
    },
  • {
    • "id": "ra125eqBFpETrMwu80g4",
    • "label": "Organization administrator",
    • "type": "ORG_ADMIN",
    • "status": "ACTIVE",
    • "created": "2019-02-06T16:17:40.000Z",
    • "lastUpdated": "2019-02-06T16:17:40.000Z",
    • "assignmentType": "USER",
    },
  • {
    • "id": "gra25fapn1prGTBKV0g4",
    • "label": "API Access Management administrator",
    • "type": "API_ACCESS_MANAGEMENT_ADMIN",
    • "status": "ACTIVE",
    • "created"": "2019-02-06T16:20:57.000Z",
    • "lastUpdated"": "2019-02-06T16:20:57.000Z",
    • "assignmentType"": "GROUP",
    }
]

Assign a user role
OAuth 2.0: okta.roles.manage

Assigns a standard role to a user.

You can also assign a custom role to a user, but the preferred method to assign a custom role to a user is to create a binding between the custom role, the resource set, and the user. See Create a Role Resource Set Binding.

Notes:

  • The request payload is different for standard and custom role assignments.
  • For IAM-based standard role assignments, use the request payload for standard roles. However, the response payload for IAM-based role assignments is similar to the custom role's assignment response.
Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
query Parameters
disableNotifications
boolean
Default: false

Setting this to true grants the user third-party admin status

Request Body schema: application/json
required
One of:
type
string

Specify the standard or IAM-based role type. See standard roles.

Responses
201

Created

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/users/{userId}/roles
Request samples
application/json
{
  • "type": "string"
}
Response samples
application/json
{
  • "id": "ra1b8anIk7rx7em7L0g4",
  • "label": "Super Organization administrator",
  • "type": "SUPER_ADMIN",
  • "status": "ACTIVE",
  • "created": "2015-09-06T15:28:47.000Z",
  • "lastUpdated": "2015-09-06T15:28:47.000Z",
  • "assignmentType": "USER",
}

Retrieve a user role assignment
OAuth 2.0: okta.roles.read

Retrieves a role assigned to a user (identified by userId). The roleAssignmentId parameter is the unique identifier for either a standard role assignment object or a custom role resource set binding object.

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/roles/{roleAssignmentId}
Request samples
Response samples
application/json
{
  • "id": "ra1b8anIk7rx7em7L0g4",
  • "label": "Super Organization administrator",
  • "type": "SUPER_ADMIN",
  • "status": "ACTIVE",
  • "created": "2015-09-06T15:28:47.000Z",
  • "lastUpdated": "2015-09-06T15:28:47.000Z",
  • "assignmentType": "USER",
}

Unassign a user role
OAuth 2.0: okta.roles.manage

Unassigns a role assignment (identified by roleAssignmentId) from a user (identified by userId)

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/users/{userId}/roles/{roleAssignmentId}
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": [ ]
}

Retrieve all User Role Governance Sources
OAuth 2.0: okta.roles.read

Retrieves the governance sources of a Role (identified by roleAssignmentId) that's assigned to a User (identified by userId)

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/roles/{roleAssignmentId}/governance
Request samples
Response samples
application/json
{}

Retrieve a User Role Governance Source
OAuth 2.0: okta.roles.read

Retrieves a Governance Source (identified by grantId) for a Role (identified by roleAssignmentId) that's assigned to a User (identified by userId)

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
grantId
required
string

Grant ID

Example: iJoqkwx50mrgX4T9LcaH
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/roles/{roleAssignmentId}/governance/{grantId}
Request samples
Response samples
application/json
{}

Retrieve the User Role Governance Source Resources
OAuth 2.0: okta.roles.read

Retrieves the resources of a Governance Source (identified by grantId) for a Role (identified by roleAssignmentId) that's assigned to a User (identified by userId)

Request
path Parameters
userId
required
string

ID of an existing Okta user

Example: 00ub0oNGTSWTBKOLGLNR
roleAssignmentId
required
string

The id of the role assignment

Example: JBCUYUC7IRCVGS27IFCE2SKO
grantId
required
string

Grant ID

Example: iJoqkwx50mrgX4T9LcaH
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/users/{userId}/roles/{roleAssignmentId}/governance/{grantId}/resources
Request samples
Response samples
application/json
{}