Role Assignments

The Role Assignments APIs allow you to assign custom roles, and designate third-party admin status, to users, groups and public client apps.

List all Assigned Roles of Group
OAuth 2.0: okta.roles.read

Lists all assigned roles of group identified by groupId

Request
path Parameters
groupId
required
string

The id of the group

Example: 00g1emaKYZTWRYYRRTSK
query Parameters
expand
string
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/groups/{groupId}/roles
Request samples 
Response samples 
application/json
[
  • {
    • "assignmentType": "GROUP",
    • "created": "2019-08-24T14:15:22Z",
    • "description": "string",
    • "id": "string",
    • "label": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "status": "ACTIVE",
    • "type": "API_ACCESS_MANAGEMENT_ADMIN",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
Assign a Role to a Group
OAuth 2.0: okta.roles.manage
Assigns a role to a group


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
query Parameters
disableNotifications
boolean
Setting this to true grants the group third-party admin status


 
Request Body schema: application/json
required
type
string (RoleType) 
Standard role type


 Enum: Description
API_ACCESS_MANAGEMENT_ADMIN
Access Management Administrator


API_ADMIN
Access Management Administrator


APP_ADMIN
Application Administrator


CUSTOM
Custom label specified by the client


GROUP_MEMBERSHIP_ADMIN
Group Membership Administrator


HELP_DESK_ADMIN
Help Desk Administrator


MOBILE_ADMIN
Mobile Administrator


ORG_ADMIN
Organizational Administrator


READ_ONLY_ADMIN
Read-Only Administrator


REPORT_ADMIN
Report Administrator


SUPER_ADMIN
Super Administrator


USER_ADMIN
Group Administrator


 
Responses 
200
Success


201
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/groups/{groupId}/roles
Request samples 
application/json
{
  • "type": "API_ACCESS_MANAGEMENT_ADMIN"
}
Response samples 
application/json
{
  • "assignmentType": "GROUP",
  • "created": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "label": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "type": "API_ACCESS_MANAGEMENT_ADMIN",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
Retrieve a Role assigned to Group
OAuth 2.0: okta.roles.read
Retrieves a role identified by roleId assigned to group identified by groupId


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/groups/{groupId}/roles/{roleId}
Request samples 
Response samples 
application/json
{
  • "assignmentType": "GROUP",
  • "created": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "label": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "type": "API_ACCESS_MANAGEMENT_ADMIN",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
Unassign a Role from a Group
OAuth 2.0: okta.roles.manage
Unassigns a role identified by roleId assigned to group identified by groupId


Request 
path Parameters
groupId
required
string
The id of the group


 
 Example:  00g1emaKYZTWRYYRRTSK
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/groups/{groupId}/roles/{roleId}
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 Users with Role Assignments
OAuth 2.0: okta.roles.read
Lists all users with Role Assignments


Request 
query Parameters
after
string
 
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 Roles assigned to a User
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


 
query Parameters
expand
string
 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/roles
Request samples 
Response samples 
application/json
[
  • {
    • "assignmentType": "GROUP",
    • "created": "2019-08-24T14:15:22Z",
    • "description": "string",
    • "id": "string",
    • "label": "string",
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "status": "ACTIVE",
    • "type": "API_ACCESS_MANAGEMENT_ADMIN",
    • "_embedded": {
      },
    • "_links": {
      }
    }
]
Assign a Role to a User
OAuth 2.0: okta.roles.manage
Assigns a role to a user identified by userId


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
query Parameters
disableNotifications
boolean
Setting this to true grants the user third-party admin status


 
Request Body schema: application/json
required
type
string (RoleType) 
Standard role type


 Enum: Description
API_ACCESS_MANAGEMENT_ADMIN
Access Management Administrator


API_ADMIN
Access Management Administrator


APP_ADMIN
Application Administrator


CUSTOM
Custom label specified by the client


GROUP_MEMBERSHIP_ADMIN
Group Membership Administrator


HELP_DESK_ADMIN
Help Desk Administrator


MOBILE_ADMIN
Mobile Administrator


ORG_ADMIN
Organizational Administrator


READ_ONLY_ADMIN
Read-Only Administrator


REPORT_ADMIN
Report Administrator


SUPER_ADMIN
Super Administrator


USER_ADMIN
Group Administrator


 
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": "API_ACCESS_MANAGEMENT_ADMIN"
}
Response samples 
application/json
{
  • "assignmentType": "GROUP",
  • "created": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "label": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "type": "API_ACCESS_MANAGEMENT_ADMIN",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
Retrieve a Role assigned to a User
OAuth 2.0: okta.roles.read
Retrieves a role identified by roleId assigned to a user identified by userId


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/roles/{roleId}
Request samples 
Response samples 
application/json
{
  • "assignmentType": "GROUP",
  • "created": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "label": "string",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "status": "ACTIVE",
  • "type": "API_ACCESS_MANAGEMENT_ADMIN",
  • "_embedded": {
    • "property1": { },
    • "property2": { }
    },
  • "_links": {
    • "self": {
      }
    }
}
Unassign a Role from a User
OAuth 2.0: okta.roles.manage
Unassigns a role identified by roleId from a user identified by userId


Request 
path Parameters
userId
required
string
ID of an existing Okta user


 
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/users/{userId}/roles/{roleId}
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 Roles for a Client
OAuth 2.0: okta.roles.read
Lists all Roles by clientId


Request 
path Parameters
clientId
required
string
client_id of the app


 
 Example:  52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/oauth2/v1/clients/{clientId}/roles
Request samples 
Response samples 
application/json
[]
Assign Role to Client
OAuth 2.0: okta.roles.manage
Assigns a Role to a Client


Request 
path Parameters
clientId
required
string
client_id of the app


 
 Example:  52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
Request Body schema: application/json
required
One of:
type
string
Standard role type


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


post/oauth2/v1/clients/{clientId}/roles
Request samples 
application/json
{
  • "type": "HELP_DESK_ADMIN,"
}
Response samples 
application/json
{}
Retrieve a Client Role
OAuth 2.0: okta.roles.read
Retrieves a Client Role


Request 
path Parameters
clientId
required
string
client_id of the app


 
 Example:  52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/oauth2/v1/clients/{clientId}/roles/{roleId}
Request samples 
Response samples 
application/json
{}
Unassign a Role from a Client
OAuth 2.0: okta.roles.manage
Unassigns a Role from a Client


Request 
path Parameters
clientId
required
string
client_id of the app


 
 Example:  52Uy4BUWVBOjFItcg2jWsmnd83Ad8dD
roleId
required
string
id of the Role


 
 Example:  3Vg1Pjp3qzw4qcCK5EdO
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/oauth2/v1/clients/{clientId}/roles/{roleId}
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": [ ]
}