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