Roles service


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 service supports the following endpoint 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 was invalid.
401 You weren’t authenticated to perform this operation.
403 You lack either the necessary permissions or the licensing to perform this operation.
404 The specified object doesn’t exist.

Endpoint examples

Get entitlements

You can get a list of all the defined entitlements in the PingOne platform. The following sample shows the GET /entitlements operation to return the list of all entitlements defined in the PingOne platform.

curl -X GET "https://api.pingone.com/v1/entitlements" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/entitlements"
        }
    },
    "permissions": {
        "applications:delete:application": [
            {
                "type": "PLATFORM"
            }
        ],
        "policy:update:policyset": [
            {
                "type": "PLATFORM"
            }
        ],
        "branding:delete:branding": [
            {
                "type": "PLATFORM"
            }
        ],

...

}

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 "Content-type: application/json" \
-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 "Content-type: application/json" \
-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"
        }
    }
}

Create role assignments

The permissions service provides operations to view all roles defined in the platform and manage the roles assigned to specific actors. When you assign a role to an actor, you provide the attribute values required to identify the role and designate the role assignment scope for this actor.

The following sample shows the POST /environments/{environmentId}/{actorType}/{actorId}/roleAssignments operation to update the role assignment for the actor in the specified environment resource.

curl -X POST "https://api.pingone.com/v1/environments/{environmentId}/{actorType}/{actorId}/roleAssignments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "role": {
    "id": "1813bc13-8d13-4e88-a825-d40bfe82777b",
  },
  "scope": {
    "id": "d928aa51-c194-4333-9cf5-0fd0c9b7d62f",
    "type": "ORGANIZATION"
  }
}"

The request URL identifies the environment ID, actor type (users), and actor ID. The request body specifies the role ID and the scope attribute values. The scope attribute provides the resource ID and resource type to designate the role assignment scope associated with this actor. In this sample, the scope type is ORGANIZATION and the specific organization to which the role assignment scope applies is specified in the id value.

Get role assignments

Actors in PingOne can be assigned one or more roles. You can view the roles assigned to a specific actor, and you can view the role assignment scopes that define the limitations of each role.

The GET /environments/{environmentId}/{actorType}/{actorId}/roleAssignments operation returns the list of roles assigned to the actor identified by the actor’s ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/{actorType}/{actorId}/roleAssignments" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The request URL identifies the environment ID, actor type, and the actor’s ID.

The response data for an actor with more than one role looks like this. Note that the list of permissions for the roles in this sample has been edited. The data returned from this GET request will show every permission assigned to each role.

{
  "count" : 4,
  "size" : 4,
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/environments/76777665-61cb-415a-b0f7-3c6f7a7235c3/users/986ab733-6dc8-4d3b-bc66-0cdaaed00e1f/roleAssignments"
    }
  },
  "_embedded" : {
    "roleAssignments" : [ {
      "id" : "170e554e-dd6f-427f-9115-a253e3cf3911",
      "role" : {
        "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
        "name" : "Identity Data Admin",
        "description" : "Identity Data Admin",
        "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
        "permissions" : [
         {
          "namespace" : "dir",
          "description" : "Read users"
         }
        ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "97898b41-914f-477e-88ae-df57f51ea57c",
      "role" : {
        "id" : "29ddce68-cd7f-4b2a-b6fc-f7a19553b496",
        "name" : "Environment Admin",
        "description" : "Environment Admin",
        "applicableTo" : [ "ORGANIZATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "dir",
          "description" : "Delete populations"
        }
        ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "26299e68-1c9d-40ba-801f-eb8d42d6f748",
      "role" : {
        "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
        "name" : "Identity Data Admin",
        "description" : "Identity Data Admin",
        "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "dir",
          "description" : "Update users"
        }
       ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
        "type" : "ENVIRONMENT"
      }
    }, {
      "id" : "61a7abee-1290-4633-ad97-e98c6366107c",
      "role" : {
        "id" : "29ddce68-cd7f-4b2a-b6fc-f7a19553b496",
        "name" : "Environment Admin",
        "description" : "Environment Admin",
        "applicableTo" : [ "ORGANIZATION", "ENVIRONMENT" ],
        "permissions" : [
        {
          "namespace" : "api_client_config",
          "description" : "Update or Reset secret for Client"
        }
       ]
      },
      "actor" : {
        "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
        "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
        "type" : "USER"
      },
      "scope" : {
        "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
        "type" : "ENVIRONMENT"
      }
    } ]
  }
}

The response data also shows that this actor has two roles: Environment Admin and Identity Data Admin. In addition, each of these roles is defined by two role assignment scopes. The JSON excerpt below shows the two role assignment scopes for the Identity Data Admin role.

"_embedded" : {
  "roleAssignments" : [ {
    "id" : "170e554e-dd6f-427f-9115-a253e3cf3911",
    "role" : {
      "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
      "name" : "Identity Data Admin",
      "description" : "Identity Data Admin",
      "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
      "permissions" : [
       {
        "namespace" : "dir",
        "description" : "Read users"
       }
      ]
    },
    "actor" : {
      "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
      "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
      "type" : "USER"
    },
    "scope" : {
      "id" : "07267d87-8b3f-4524-8175-b5dacd221121",
      "type" : "ENVIRONMENT"
    }
  }, {
    "id" : "26299e68-1c9d-40ba-801f-eb8d42d6f748",
    "role" : {
      "id" : "0bd9c966-7664-4ac1-b059-0ff9293908e2",
      "name" : "Identity Data Admin",
      "description" : "Identity Data Admin",
      "applicableTo" : [ "POPULATION", "ENVIRONMENT" ],
      "permissions" : [
      {
        "namespace" : "dir",
        "description" : "Read users"
      }
     ]
    },
    "actor" : {
      "id" : "986ab733-6dc8-4d3b-bc66-0cdaaed00e1f",
      "environmentId" : "76777665-61cb-415a-b0f7-3c6f7a7235c3",
      "type" : "USER"
    },
    "scope" : {
      "id" : "1c6a8c00-04e8-4573-9b32-64d6d107548c",
      "type" : "ENVIRONMENT"
    }
   }
  } ]
}

The id attribute for each scope attribute specifies a different environment resource ID.

Get one role assignment

The GET /environments/{environmentId}/{actorType}/{actorId}/roleAssignments/{roleAssignmentId} operation returns the specific role assignment assigned to the actor identified by the actor’s ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/{actorType}/{actorId}/roleAssignments/{roleAssignmentId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

Delete role assignments

The following sample shows the DELETE /environments/{environmentId}/{actorType}/{actorId}/roleAssignments/{roleAssignmentId} operation to delete the role assignment specified by its ID in the request URL. The role assignment is deleted only for the actor identified in the request URL.

curl -X DELETE "https://api.pingone.com/v1/environments/{environmentId}/{actorType}/{actorId}/roleAssignments/{roleAssignmentId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \

When successful, the DELETE request returns a code 204 No Content message.