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",
    • "_links": {}
    },
  • {
    • "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",
    • "_links": {}
    },
  • {
    • "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",
    • "_links": {}
    },
  • {
    • "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",
    • "_links"": {}
    }
]
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",
  • "_links": {}
}
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",
  • "_links": {}
}
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
{}