PingOne Advanced Identity Cloud

Manage identities

In Advanced Identity Cloud user identities are sometimes referred to as managed users or user managed objects. There are alpha users and bravo users.

To retrieve, add, change, and delete managed users, use one of the following methods:

  • In the Advanced Identity Cloud admin UI, any of the options in Identities > Manage > realm-name_user.

  • The REST interface at the context path /openidm/managed/realm-name_user.

Managed users examples

The following examples show how to retrieve, add, change, and delete users over the REST interface. For more information on all the managed user endpoints and actions, refer to the Managed users endpoint.

Retrieve IDs of all managed users in a realm

The size of the returned set can be large when there are many users in your tenant.
curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=true&_fields=_id"
{
  "result": [
    {
      "_id": "1dff18dc-ac57-4388-8127-dff309f80002",
      "_rev": "ceea2483-7f92-411e-9194-dcca0d61198e-48377"
    },
    {
      "_id": "7750881d-1622-451e-9ee5-71f7aaafcadf",
      "_rev": "ecf2cd07-f187-482e-9fa0-1127c267bce2-65781"
    },
    ...
  ],
  ...
}

Query managed users for a specific user

You can return a subset of users based on a query. If the conditions are met, then the users are returned.

The _queryFilter requires double quotes, or the URL-encoded equivalent (%22), around the search term. This example uses the URL-encoded equivalent:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22scarter%22"
{
  "result": [
    {
      "_id": "7750881d-1622-451e-9ee5-71f7aaafcadf",
      "_rev": "ecf2cd07-f187-482e-9fa0-1127c267bce2-65781",
      "userName": "scarter",
      "givenName": "Sam",
      "sn": "Carter",
      "telephoneNumber": "12345678",
      "active": "true",
      "mail": "scarter@example.com",
      "accountStatus": "active",
      "effectiveAssignments": [],
      "effectiveRoles": []
    }
  ],
  ...
}

This example uses single quotes around the URL to avoid conflicts with the double quotes around the search term:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+"scarter"'
{
  "result": [
    {
      "_id": "7750881d-1622-451e-9ee5-71f7aaafcadf",
      "_rev": "ecf2cd07-f187-482e-9fa0-1127c267bce2-65781",
      "userName": "scarter",
      "givenName": "Sam",
      "sn": "Carter",
      "telephoneNumber": "12345678",
      "active": "true",
      "mail": "scarter@example.com",
      "accountStatus": "active",
      "effectiveAssignments": [],
      "effectiveRoles": []
    }
  ],
  ...
}

Retrieve a managed user by their ID

In the following example, 7750881d-1622-451e-9ee5-71f7aaafcadf is the UUID of the user.

If you do not know the UUID of the user, you can retrieve the user by performing a search query, as described in Query managed users for a specific user.

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/7750881d-1622-451e-9ee5-71f7aaafcadf"
{
  "_id": "7750881d-1622-451e-9ee5-71f7aaafcadf",
  "_rev": "ecf2cd07-f187-482e-9fa0-1127c267bce2-65781",
  "userName": "scarter",
  "givenName": "Sam",
  "sn": "Carter",
  "telephoneNumber": "12345678",
  "active": "true",
  "mail": "scarter@example.com",
  "accountStatus": "active",
  "effectiveAssignments": [],
  "effectiveRoles": []
}

Add a user with a specific user ID

To add a user, you must provide the minimum required attributes.

To locate the minimum required attributes:

  1. From the Advanced Identity Cloud admin UI, click Native Consoles > Identity Management.

  2. Click Configure > Managed Objects > managed/realm-name_user.

  3. In the Required column, note the properties that have required marked.

    1. To create a user, these are the minimum attributes you must present.

If you create an object using PUT, the ID you assign must be a UUID, for example, 4cf65bb9-baa4-4488-aa73-216adf0787a1.
curl \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "If-None-Match: *" \
--request PUT \
--data '{
  "userName": "bjackson",
  "sn": "Jackson",
  "givenName": "Barbara",
  "mail": "bjackson@example.com",
  "telephoneNumber": "082082082",
  "password": "Passw0rd"
}' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/4cf65bb9-baa4-4488-aa73-216adf0787a1"
{
  "_id": "4cf65bb9-baa4-4488-aa73-216adf0787a1",
  "_rev": "ceea2483-7f92-411e-9194-dcca0d61198e-51099",
  "userName": "bjackson",
  "sn": "Jackson",
  "givenName": "Barbara",
  "mail": "bjackson@example.com",
  "telephoneNumber": "082082082",
  "accountStatus": "active",
  "effectiveAssignments": [],
  "effectiveRoles": []
}

Add a user with a system-generated ID

To add a user, you must provide the minimum required attributes.

To locate the minimum required attributes:

  1. From the Advanced Identity Cloud admin UI, click Native Consoles > Identity Management.

  2. Click Configure > Managed Objects > managed/realm-name_user.

  3. In the Required column, note the properties that have required marked.

    1. To create a user, these are the minimum attributes you must present.

In this instance, Advanced Identity Cloud will create a UUID for you.

curl \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{
  "userName": "pjensen",
  "sn": "Jensen",
  "givenName": "Pam",
  "mail": "pjensen@example.com",
  "telephoneNumber": "082082082",
  "password": "Passw0rd"
}' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_action=create"
{
  "_id": "4121ae44-7bf4-4dcb-b853-cfc8b5b8582c",
  "_rev": "ceea2483-7f92-411e-9194-dcca0d61198e-51129",
  "userName": "pjensen",
  "sn": "Jensen",
  "givenName": "Pam",
  "mail": "pjensen@example.com",
  "telephoneNumber": "082082082",
  "accountStatus": "active",
  "effectiveAssignments": [],
  "effectiveRoles": []
}

Update a user

This example checks whether user bjackson exists, then replaces the telephone number attribute with the new data provided in the request body:

curl \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '[
  {
    "operation": "replace",
    "field": "/telephoneNumber",
    "value": "0763483726"
  }
]' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_action=patch&_queryFilter=userName+eq+'bjackson'"
{
  "userName": "bjackson",
  "sn": "Jackson",
  "givenName": "Barbara",
  "mail": "bjackson@example.com",
  "telephoneNumber": "0763483726",
  "accountStatus": "active",
  "effectiveAssignments": [],
  "effectiveRoles": [],
  "_rev": "ceea2483-7f92-411e-9194-dcca0d61198e-51153",
  "_id": "4cf65bb9-baa4-4488-aa73-216adf0787a1"
}

Delete a user

To delete a user, all you need is the UUID.

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/4cf65bb9-baa4-4488-aa73-216adf0787a1"
{
  "_id": "4cf65bb9-baa4-4488-aa73-216adf0787a1",
  "_rev": "ceea2483-7f92-411e-9194-dcca0d61198e-51153",
  "userName": "bjackson",
  "sn": "Jackson",
  "givenName": "Barbara",
  "mail": "bjackson@example.com",
  "telephoneNumber": "0763483726",
  "accountStatus": "active",
  "effectiveAssignments": [],
  "effectiveRoles": []
}