PingOne Platform APIs

User Role Assignments

The users role assignments endpoint implements functions to create, read, and delete the role assignments associated with user resources. For more information about roles and the permissions associated with each role, refer to Roles.

Role assignments are defined by the role itself, and at a more granular level by the scope attribute associated with the role assignment. The role assignment scope identifies the type of platform resource that defines the scope, and the id of the specific resource to which the scope applies. The following sample shows the scope attribute, which includes the resource type and id attributes. In this case, the scope is restricted to the environment resource identified by its id.

{
  "scope": {
   "id": "d928aa51-c194-4333-9cf5-0fd0c9b7d62f",
   "type": "ENVIRONMENT"
   }
}

Role assignment scopes can be:

  • Organization

  • Environment

  • Population

  • Group

  • Application

Users role assignments data model

Property Type Required Mutable Description

environment.id

String

N/A

Read-only

The environment associated with the user.

id

String

N/A

Read-only

Specifies the user role assignment ID.

readOnly

Boolean

Optional

Mutable

Specifies whether this role assignment can be deleted by the current actor.

role.id

String

Required

Mutable

The role ID.

scope.id

String

Required

Mutable

The role assignment scope ID. When this is an application ID, because an application ID is guarenteed to be globally unique (across all environments), the application ID here eliminates the need to also specify the application environment ID.

scope.type

String

Required

Mutable

The type of resource defining the scope of the Role assignment. Options are ORGANIZATION, ENVIRONMENT, POPULATION, GROUP, and APPLICATION. GROUP scope of the role assignment can be applied only to groups and users.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

404

The requested resource was not found.

User role assignment errors

In addition to the general error codes, user role assignment operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST /users/{ID}/roleAssignments request body omits role, role.id, scope.id, or scope.type, supplies a scope.id that is not a UUID, assigns a role that does not exist in the environment, or assigns a role that does not support the requested scope type

Details: Describes the failing property, such as A valid Role is required for an omitted role or role.id, A valid Scope id is required for an omitted scope.id, A valid Scope type is required for an omitted scope.type, Scope id is not a valid UUID. for a scope.id that is not a UUID, Role with such UUID does not exist. for a role that does not exist in the environment, or Provided scope is not applicable to role. for a role that does not support the requested scope type, for example Validation Error : [scope.id Scope id is not a valid UUID.]

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST /users/{ID}/roleAssignments request assigns a role the user already has at the same scope or at a scope that contains or is contained by the requested scope. Indirect (group‑inherited) assignments do not count as duplicates

Details: May not assign duplicate Role

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: The actor is not allowed to assign the role, or to remove it on DELETE /users/{ID}/roleAssignments/{roleAssignmentID}: the request targets the actor’s own user, the actor does not have the role at the same or a broader scope, a custom role is scoped outside the environment it belongs to, or, for POST /users/{ID}/roleAssignments only, the requested scope is outside the actor’s organization

Details: Describes the failed privilege check, such as May not change role assignments for self, Must have role at the same or broader scope, May only scope custom roles for environment they live in, or May not assign roles for scopes outside the organization

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: The access token does not contain the claims needed to identify the actor

Details: Can not determine actor from claims

400

REQUEST_FAILED

None

Message: Limit exceeded for role assignments per actor. Limit is <maximum>

When and details

When: A POST /users/{ID}/roleAssignments request would exceed the maximum number of role assignments for the user

Details: None.

400

REQUEST_FAILED

None

Message: Limit exceeded for role assignments with <scopeType> scope type per user. Limit is <maximum>

When and details

When: A POST /users/{ID}/roleAssignments request with a POPULATION, APPLICATION, or GROUP scope type would exceed the maximum number of role assignments of that scope type for the user

Details: None.

400

REQUEST_FAILED

INVALID_FILTER or INVALID_PARAMETER

Message: The request could not be completed. One or more validation errors were in the request. for a filter or order rejection from the shared scaffolding handlers, or The request could not be completed. There was an issue processing the request. for a service-level filter rejection

When and details

When: GET /users/{ID}/roleAssignments uses an unsupported or malformed filter or order query parameter. The filter parameter supports role.id, scope.type, and type with eq, and scope.name with co; the order parameter supports scope.name, scope.type, and scope.environment.name

Details: Describes the rejected filter or order, such as The filter operator was invalid or not supported., The filter attribute was invalid or does not support filtering., '<value>' is not a valid scope type. Valid scope types are: [ORGANIZATION, ENVIRONMENT, POPULATION, APPLICATION, GROUP], '<value>' is not a valid type. Valid types are: [DIRECT, INDIRECT], Unable to convert value: '<value>' into a 'uuid'., or the order parameter listing the supported fields

400

INVALID_REQUEST

None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A path identifier cannot be parsed as a UUID

Details: None.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the permissions:read:userRoleAssignments permission (GET operations) or the permissions:update:userRoleAssignments permission (POST and DELETE operations), or is not authorized for the target user’s population or group scope

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: The user ID in the request URL does not exist in the environment, or the referenced role assignment does not exist

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: GET /users/{ID}/roleAssignments/{roleAssignmentID} references a role assignment that belongs to a different actor than the user in the request URL, or is not a user role assignment

Details: None.