Role Assignments

These APIs allow you to assign custom roles to user and groups, as well as designate Third-Party Administrator status to a user or group.

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
type
string (RoleType) 
 Enum: {"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
 
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
 
query Parameters
disableNotifications
boolean
Setting this to true grants the user third-party admin status


 
Request Body schema: application/json
type
string (RoleType) 
 Enum: {"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
 
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
 
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": [ ]
}