User role assignments


User role assignments API operations

The user role assignments endpoints support the following operations:

Users role assignments endpoints

For hands-on experience with the users 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.

Users data model

Property Description
accountId A string that specifies the user’s account ID, which is optional. This may be explicitly set to null when updating a user to unset it. This attribute is organization-specific and has no special meaning within the PingOne platform.
address.countryCode A string that specifies the country name component. When specified, the value must be in ISO 3166-1 “alpha-2” code format [ISO3166]. For example, the country codes for the United States and Sweden are “US” and “SE”, respectively.
address.locality A string that specifies the city or locality component of the address.
address.postalCode A string that specifies the zip code or postal code component of the address.
address.region A string that specifies the state or region component of the address.
address.streetAddress A string that specifies the full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute may contain newlines.
createdAt The time the resource was created.
email A string that specifies the user’s email address, which must be provided and valid.
enabled A read-only boolean attribute that specifies whether the user is enabled. This attribute is set to ‘true’ by default when the user is created.
environment.id A string that specifies the environment resource’s unique identifier associated with the user.
externalId A string that specifies an identifier for the user resource as defined by the provisioning client. This is optional. This may be explicitly set to null when updating a user to unset it. The externalId attribute may simplify the correlation of the user in PingOne with the user’s account in another system of record. The platform does not use this attribute directly in any way, but it is used by Ping Identity’s Data Sync product.
id A string that specifies the user resource’s unique identifier.
lifecycle.status A string that specifies information about the account lifecycle. Options for status are ACCOUNT_OK and VERIFICATION_REQUIRED. This property value is only allowed to be set when importing a user to set the initial account status. If the initial status is set to VERIFICATION_REQUIRED and an email address is provided, a verification email is sent.
locale A string that specifies the user’s default location, which is optional. This may be explicitly set to null when updating a user to unset it. This is used for purposes of localizing such items as currency, date time format, or numerical representations. If provided, a valid value is a language tag as defined in RFC 5646. The following are example tags: fr, en-US, es-419, az-Arab, man-Nkoo-GN.
mfaEnabled A read-only boolean attribute that specifies whether multi-factor authentication is enabled. This attribute is set to ‘false’ by default when the user is created.
mobilePhone A string that specifies the user’s mobile phone number, which is optional. This might also match the primaryPhone attribute. This may be explicitly set to null when updating a user to unset it. If provided, it must consist of a leading plus sign, 1 to 3-digit country code, dot separator, 4 to 14-digit phone number, and optional 1 to 8-digit extension (for example, +1.3034682900x1234).
name.family A string that specifies the family name of the user, or Last in most Western languages (for example, ‘Jensen’ given the full name ‘Ms. Barbara J Jensen, III’). This may be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen. It can have a length of no more than 256 characters.
name.formatted A string that specifies the fully formatted name of the user (for example ‘Ms. Barbara J Jensen, III’). This can be explicitly set to null when updating a name to unset it.
name.given A string that specifies the given name of the user, or First in most Western languages (for example, ‘Barbara’ given the full name ‘Ms. Barbara J Jensen, III’). This may be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen. It can have a length of no more than 256 characters.
name.honorificPrefix A string that specifies the honorific prefix(es) of the user, or title in most Western languages (for example, ‘Ms.’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it.
name.honorificSuffix A string that specifies the honorific suffix(es) of the user, or suffix in most Western languages (for example, ‘III’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it.
name.middle A string that specifies the the middle name(s) of the user (for exmple, ‘Jane’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it. Valid characters consists of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen. It can have a length of no more than 256 characters.
nickname A string that specifies the user’s nickname, which is optional. This can be explicitly set to null when updating a user to unset it. Valid characters consists of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen. It can have a length of no more than 256 characters.
photo.href A string that specifies the URI that is a uniform resource locator (as defined in Section 1.1.3 of RFC 3986) that points to a resource location representing the user’s image. This can be removed from a user by setting the photo attribute to null. If provided, the resource must be a file (for example, a GIF, JPEG, or PNG image file) rather than a web page containing an image. It must also have a scheme of HTTP or HTTPS.
population.id A string that specifies the identifier of the population resource associated with the user.
preferredLanguage A string that specifies the user’s preferred written or spoken languages, which are optional. This may be explicitly set to null when updating a user to unset it. If provided, the format of the value is the same as the HTTP Accept-Language header field (not including Accept-Language:) and is specified in Section 5.3.5 of RFC 7231. For example: en-US, en-gb;q=0.8, en;q=0.7.
primaryPhone A string that specifies the user’s primary phone number, which is optional. This might also match the mobilePhone attribute. This may be explicitly set to null when updating a user to unset it. If provided, it must consist of a leading plus sign, 1 to 3-digit country code, dot separator, 4 to 14-digit phone number, and optional 1 to 8-digit extension (for example, +1.3034682900x1234).
timezone A string that specifies the user’s time zone, which is optional. This can be explicitly set to null when updating a user to unset it. If provided, it must conform with the IANA Time Zone database format [RFC6557], also known as the “Olson” time zone database format [Olson-TZ] for example, “America/Los_Angeles”).
title A string that specifies the user’s title, which is optional, such as “Vice President”. This can be explicitly set to null when updating a user to unset it.
type A string that specifies the user’s type, which is optional. This can be explicitly set to null when updating a user to unset it. This attribute is organization-specific and has no special meaning within the PingOne platform. It could have values of “Contractor”, “Employee”, “Intern”, “Temp”, “External”, and “Unknown”.
updatedAt The time the resource was last updated.
username A string that specifies the user name, which must be provided and must be unique within an environment. The username must either be a well-formed email address or a string of any Unicode letter, mark (for example, accent, umlaut), dot, underscore, or hyphen. It can have a length of no more than 128 characters.

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.
409 A resource with the specified name already exists.

Endpoint examples

Create user role assignments

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

The following sample shows the POST /environments/{environmentId}/users/{userId}/roleAssignments operation to update the role assignment for the user in the specified environment resource.

curl -X POST "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/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 and user 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.

For more information about role assignment scopes, see Roles.

Get user role assignments

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

The GET /environments/{environmentId}/users/{userId}/roleAssignments operation returns the list of roles assigned to the user identified by the user’s ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/roleAssignments" \
-H "Authorization: Bearer jwtToken"

The request URL identifies the environment ID and the user’s ID.

The response data for a user 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 user 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 user role assignment

The GET /environments/{environmentId}/users/{userId}/roleAssignments/{roleAssignmentId} operation returns the specific role assignment assigned to the user identified by the user’s ID.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/users/{userId}/roleAssignments/{roleAssignmentId}" \
-H "Authorization: Bearer jwtToken"

Delete role assignments

The following sample shows the DELETE /environments/{environmentId}/users/{userId}/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}/users/{userId}/roleAssignments/{roleAssignmentId}" \
-H "Authorization: Bearer jwtToken" \

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