Roles


User roles

The ability to perform an action using PingOne APIs is determined by roles. For example, when you initiate a request to a PingOne endpoint, you must have the permissions required by the endpoint to execute the request. Permissions in PingOne are associated with the following roles:

  • Organization Admin

    The Organization Admin role provides user permissions to perform the following PingOne API operations:

    • Read organization resources.
    • Create, read, update, delete, and promote environment resources.
    • Read license resources and update a license’s mutable properties.
  • Environment Admin

    The Environment Admin role provides user permissions to perform the following PingOne API operations:

    • Read and promote environments
    • Read license resources
    • Read, create, update, and delete population resources
    • Read organization resources
    • Read and update password policy resources
    • Read and create notifications resources and email resources
    • Update and delete branding resources
    • Read audit reporting activities resources
    • Read, create, update, and delete sign-on policy resources
    • Read and update schema resources
    • Read, update, and delete mapping resources
    • Read and update application role assignments resources
    • Read, create, update, and delete application (client) resources
    • Read and update an application’s client_secret resources
    • Read, create, update, and delete application grant resources
    • Read, create, update, and delete application attribute resources
    • Read, create, update, and delete application role assignments resources
    • Read, create, update, and delete application sign-on policy assignments resources
    • Read, create, update, and delete application push credentials resources
    • Read, create, update, and delete certificate and key resources
    • Read, create, update, and delete identity provider resources
    • Read, create, update, and delete resource entity resources
    • Read, create, update, and delete resource scope resources
  • Identity Data Admin

    The Identity Data Admin role provides user permissions to perform the following PingOne API operations:

    • Read, create, update, and delete user resources
    • Read, create, update, and delete user role assignments resources
    • Read, create, update, and delete device management resources
    • Read and delete linked accounts resources
    • Read, create, update, and delete pairing key resources
    • Read user role assignments
    • Assign identity resources
    • Read license resources
    • Read certificate resources
    • Update user password resources
    • Read user password state resources
    • Read password policy resources
    • Read audit reporting activities resources
    • Read schema resources
  • Client Application Developer

    The Client Application Developer role provides user permissions to perform the following PingOne API operations:

    • Read, create, update, and delete application (client) resources
    • Read and update an application’s client_secret resources
    • Read, create, update, and delete application grant resources
    • Read, create, update, and delete application attribute resources
    • Read, create, update, and delete application role assignments resources
    • Read, create, update, and delete application sign-on policy assignments resources
    • Read, create, update, and delete application push credentials resources
    • Read, create, update, and delete resource entity resources
    • Read, create, update, and delete scope resources
    • Read, create, update, and delete identity provider resources
    • Read schema resources
    • Read organization resources

Automatic role assignments

Role assignments determine access to PingOne APIs. When an application or user creates a new PingOne resource over which roles can be assigned, they are assigned all possible roles that can be assigned for the environment or population. For example, if an actor creates a new environment, the actor receives the Environment Admin, Identity Data Admin, and the Client Application Developer roles over that new environment. If the actor already has an existing organization-level Environment Admin role, the Environment Admin role would not be assigned again to the actor. Likewise, if the actor creates a new population, the actor receives the Identity Data Admin role automatically (unless the actor already has that assigned role).

Users and applications cannot create actors that have more privileges than the user or application itself. For example, to create a user or an application that has Environment Admin privileges, the actor assigning roles must also have Environment Admin privileges. The actor (user or application) assigning roles must have the permissions that they are trying to assign. The requesting user or application must have the same (or broader) role assignments as the target actor’s role assignments.

When creating PingOne resources, the following roles are assigned to the actor automatically when these PingOne entities are created:

  • Environments

    Environment Admin: Assigned for the created environment at the environment level, if the actor does not already have the Environment Admin role at the parent organization level.

    Identity Data Admin: Assigned for the created environment at the environment level.

    Client Application Developer: Assigned for the created environment at the environment level.

  • Populations

    Identity Data Admin: Assigned for the created population at the population level, if the actor does not already have the Identity Data Admin role at the parent environment level.

Roles API operations

The roles endpoints support the following operations:

For hands-on experience with the roles API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Roles data model

Property Description
actor.id A string that specifies the ID of the actor.
actor.environmentId A string that specifies the ID of the environment in which the actor exists.
actor.type A string that specifies the type of the actor. Options are users and clients.
description A string that specifies the description of the resource.
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the resource’s unique identifier.
name A string that specifies the resource name.
role.applicableTo A string that specifies the scope to which the role applies.
role.description A string that specifies the description of the role.
role.id A string that specifies the ID of the role.
role.permissions A string that specifies the set of permissions assigned to the role.
role.permissions.classifier A string that specifies the resource for which the permission is applicable.
role.permissions.description A string that specifies the description of what the permission enables for the role.
role.scope.id A string that specifies the ID of the role assignment scope.
role.scope.type A string that specifies the type of resource defining the scope of the role assignment. Options are PLATFORM, ORGANIZATION, ENVIRONMENT, POPULATION, and ACTOR.
type A string that specifies the type of resource. 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.

Endpoint examples

Get roles

You can get a list of all the defined roles in the PingOne platform available for assignment. The following sample shows the GET /roles operation to return each platform role and the list of all permissions associated with the role.

curl -X GET "https://api.pingone.com/v1/roles" \
-H "Authorization: Bearer jwtToken"

Get one role

If you want to get information on just one specific platform role, the GET /roles/{roleId} operation returns the role name, description, ID, and the list of permissions associated with the role ID you submitted in the request URL.

curl -X GET "https://api.pingone.com/v1/roles/{roleId}" \
-H "Authorization: Bearer jwtToken"

The response data for a specific role looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/roles/1813bc13-8d13-4e88-a825-d40bfe82777b"
    }
  },
  "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
  "name": "Organization Admin",
  "description": "Organization Admin",
  "applicableTo": [
    "ORGANIZATION"
  ],
  "permissions": [
    {
      "classifier": "organization",
      "description": "Read organizations"
    },
    {
      "classifier": "environment",
      "description": "Delete environment"
    },
    {
      "classifier": "environment",
      "description": "Promote environment"
    },
    {
      "classifier": "mutableProperties",
      "description": "Update licenses' mutable properties"
    },
    {
      "classifier": "key",
      "description": "Create a key"
    },
    {
      "classifier": "license",
      "description": "Read licenses"
    },
    {
      "classifier": "environment",
      "description": "Create environment"
    },
    {
      "classifier": "environmentLicense",
      "description": "Update environment licenses"
    },
    {
      "classifier": "environment",
      "description": "Update environment"
    },
    {
      "classifier": "environment",
      "description": "Read environments"
    }
  ]
}