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

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