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
required
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
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) 
 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
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": [ ]
}