PingOne Platform APIs

Custom Admin Roles

A Custom Admin role is an environment-level resource that consists of a set of permissions that can be edited by administrators. A custom role can be assigned to an individual user, group, worker application, or PingFederate Gateway for a specific scope (scope). The scope can be at the organization level, environment level, or population level. The role assignment also specifies the assignee, the actor who is assigned the role for the designated scope.

Role assignments determine access to PingOne APIs.

Administrators must have the Custom Role Admin permissions to create, update, and delete custom roles. The Org Admin and the Custom Role Admin roles include these permissions.

Custom admin role assignments

Role assignments for custom roles follow these common scenarios:

  1. The admin assigns the custom role to someone in the same environment because they have that custom role.

  2. The admin assigns a custom role to someone in the same environment because the role they have is specified in the canBeAssignedBy attribute of the custom role.

  3. The admin assigns a custom role to someone in a different environment because the role and actor exist in a different environment. This is possible because the admin assigning has scope (scope) over the different environment through a PingOne role, which is specified in the custom role’s canBeAssignedBy property.

To summarize these scenarios, the actor can assign a custom role to others for a specific scope only if one or more of the following conditions are true:

  • The actor already has the same role for the scope or parent scope.

  • The actor has a role that is specified in the canBeAssignedBy property of the custom role for the scope or parent scope.

To assign an admin role to a group, refer to Group Role Assignments.

To assign an admin role to a specific user, refer to User Role Assignments.

To assign an admin role to a Worker app, refer to Configure roles for a worker application in the PingOne Admin documentation.

For additional examples on assigning custom roles, refer to Custom Roles Scenarios in the PingOne Admin documentation.

Custom admin role restrictions

There are additional restrictions for using custom admin roles (these restrictions do not apply to the built-in roles).

  • Custom admin roles are not supported for PingOne Davinci at this time.

  • Custom admin roles can only be assigned at the organization level to users, groups, applications, and gateways in the administrators environment.

  • Custom roles created in any non-administrators environment can only be assigned against resources within that environment (or the entire environment).

Roles and Permissions

See PingOne Permissions by Identifier for the permission identifiers and descriptions. This information is returned by Read All Built-in Admin Roles.

You can also find permissions by PingOne Permissions by Service and PingOne Permissions by Resource.

PingFederate roles

See PingFederate SSO admin permissions for the applicable PingFederate roles.

Filtering data

The Read All Custom Admin Roles request supports SCIM filtering expressions. The query filter can be appended to the request URL to fine-tune the response data. For example, the following filter returns only the custom roles:

GET {{apiPath}}/v1/environments/{{envID}}/roles?filter=%28type+eq+%22CUSTOM%22%29

These SCIM operators can be applied to the following attributes:

eq (equal to)

Supported attributes: type

Custom administrator roles data model

Property Type Required Mutable Description

applicableTo

String[]

Required

Immutable

The scope types to which the role can be applied. Options are ORGANIZATION, ENVIRONMENT, POPULATION, APPLICATION, and GROUP. GROUP scope of the role assignment can be applied only to groups and users.

canAssign

Object

Read only

Immutable

A relationship that specifies if an actor is assigned the current custom role for a scope, then the actor can assign any of this set of roles to another actor for the same scope or sub-scope. This capability is derived from the canBeAssignedBy property.

canBeAssignedBy

Object

Required

Mutable

A relationship that determines whether a user assigned to one of this set of roles for a scope can assign the current custom role to another user for the same scope or sub-scope.

description

String

Optional

Mutable

The description of the role.

environment.id

String

N/A

Read-only

The environment resource’s unique identifier associated with the resource.

id

String

N/A

Read-only

The resource’s unique identifier.

name

String

Required

Mutable

The role name.

permissions

String

Required

Mutable

The set of permissions assigned to the role.

type

String

N/A

Read only

A value that indicates whether the role is a built-in role or a custom role. Options are PLATFORM and CUSTOM.

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.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

Custom admin role errors

In addition to the general error codes, custom admin role operations can return the following errors:

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

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

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

When and details

When: A POST or PUT /roles request omits name, applicableTo, or permissions (or leaves name blank), or includes an applicableTo value other than ORGANIZATION, ENVIRONMENT, POPULATION, APPLICATION, or GROUP

Details: name is required, applicableTo is required, permissions are required, or The only supported scope types are: ORGANIZATION, ENVIRONMENT, POPULATION, APPLICATION, GROUP, for example:

Validation Error : [applicableTo The only supported scope types are: ORGANIZATION, ENVIRONMENT, POPULATION, APPLICATION, GROUP]

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>] (the BindingResult is thrown as MethodArgumentNotValidException, so the top‑level message uses the Validation Error : [permissions <message>] form)

When and details

When: A POST or PUT /roles request includes a permission ID that the service does not recognize as available for custom roles (unknown to the permission registry or hidden by a feature flag)

Details: Unknown permissions detected: <permissionIds>, a sorted comma‑separated list of the rejected permission IDs, for example Validation Error : [permissions Unknown permissions detected: <permissionIds>].

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 /roles request creates a role with a name that duplicates an existing built‑in or custom role in the environment, or a PUT /roles/{ID} request renames the role to one that does

Details: "<name>" is not a unique role name

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A POST or PUT /roles request sets applicableTo to include ORGANIZATION in an environment that is not enabled to assign custom roles everywhere

Details: Roles cannot be scoped to ORGANIZATION in this environment

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A PUT /roles/{ID} request adds a permission while the actor holds the role being changed. The actor can only add permissions to a role they do not have assigned themselves (an internal client is exempt)

Details: May not change roles for self

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 (applies to PUT /roles/{ID})

Details: Can not determine actor from claims

400

REQUEST_FAILED

None

Message: Limit exceeded for custom roles per environment. Limit is <maximum>

When and details

When: A POST /roles request would exceed the maximum number of custom roles for the environment. The limit is checked after the name-uniqueness check, so the limit row only fires when the name is also unique

Details: None.

400

INVALID_REQUEST

None

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

When and details

When: A path identifier cannot be parsed as a UUID

Details: None.

400

INVALID_REQUEST

INVALID_VALUE

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

When and details

When: The request body cannot be deserialized as JSON (for example, an invalid canBeAssignedBy relationship ID)

Details: Invalid value for attribute., with the target set to the field path for a field conversion error. Otherwise no detail is returned.

400

REQUEST_FAILED

INVALID_FILTER

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

When and details

When: GET /roles uses a filter on an attribute other than type, or on a type value other than PLATFORM or CUSTOM

Details: Filter by type must be one of the: [PLATFORM, CUSTOM] or Invalid attribute: <attribute>

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:roles permission (GET operations), the permissions:create:roles permission (POST), the permissions:update:roles permission (PUT), or the permissions:delete:roles permission (DELETE)

Details: None.

404

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request. The top‑level code is INVALID_DATA even though the HTTP status is 404 (the handler resolves the status from the exception but builds the body from the INVALID_VALUE detail mapping).

When and details

When: GET /roles/{roleID} references a custom role that does not exist in the environment, or PUT /roles/{roleID} references a role that does not exist (update returns the same exception before validation). DELETE /roles/{roleID} raises the same exception when the role is absent

Details: There is no role with id '<roleId>' in the environment '<environmentId>'
Related topics