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:

    • Assign, read, and update organization resources.
    • Assign, create, delete, update, and promote environment resources.
  • Environment Admin

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

    • Assign, create, delete, update, and promote environments
    • Assign identity resources
    • Read 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 and update sign-on policy resources
    • Read and update schema 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
    • Assign identity resources
    • Read, create, update and delete population 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:

    • Assign, 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 resource entity resources
    • Read, create, update, and delete scope resources
    • Read schema resources

Roles are defined at a more granular level by the scope attribute. 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 organization resource identified by its id.

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

Role assignment scope types include:

  • Platform

    This scope type designates a platform-level assignment scope for the role.

  • Organization

    This scope type designates an organization resource as the assignment scope of the role.

  • Environment

    This scope designates an environment resource as the assignment scope of the role.

  • Population

    This scope designates a population resource as the assignment scope of the role.

  • Actor

    This scope designates an actor resource (users or applications) as the assignment scope of the role.

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:

{
    "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
    "name": "Organization Admin",
    "description": "Organization Admin",
    "applicableTo": [
        "ORGANIZATION"
    ],
    "permissions": [
        ...

        {
            "namespace": "orgmgt",
            "description": "Update environment"
        },
        {
            "namespace": "orgmgt",
            "description": "Create organization"
        },
        {
            "namespace": "orgmgt",
            "description": "Create environment"
        },

        ...
    ],
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/roles/1813bc13-8d13-4e88-a825-d40bfe82777b"
        }
    }
}