--- title: Users description: User objects that are managed by IDM are called managed users. component: pingidm version: 8.1 page_id: pingidm:objects-guide:users canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/users.html keywords: ["Data Object Model", "Users", "Identities"] section_ids: managed_users_examples: Managed users examples retrieve_the_ids_of_all_managed_users_in_the_repository: Retrieve the IDs of all managed users in the repository query_managed_users_for_a_specific_user: Query managed users for a specific user retrieve_a_managed_user_by_their_id: Retrieve a managed user by their ID add_a_user_with_a_specific_user_id: Add a user with a specific user ID add_a_user_with_a_system_generated_id: Add a user with a system-generated ID update_a_user: Update a user delete_a_user: Delete a user --- # Users User objects that are managed by IDM are called *managed users*. For a JDBC repository, IDM stores managed users in the `managedobjects` table. A second table, `managedobjectproperties`, serves as the index table. IDM provides RESTful access to managed users, at the context path `/openidm/managed/user`. You can add, change, and delete managed users using the admin UI or over the REST interface. To use the admin UI, select Manage > User. If you are viewing users through the admin UI, the User List page supports specialized filtering with the Advanced Filter option. This lets you build many of the queries shown in [Define and call data queries](queries.html). ## Managed users examples The following examples show how to add, change, and delete users over the REST interface. For a reference of all managed user endpoints and actions, refer to the [Managed users](../rest-api-reference/endpoints/rest-managed-users.html) endpoint. You can also use the [REST API Explorer](../rest-api-reference/api-explorer.html) as a reference to the managed object REST API. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Some examples in this documentation use client-assigned IDs (such as `bjensen` and `scarter`) when creating objects because it makes the examples easier to read. If you create objects using the admin UI, they are created with server-assigned IDs (such as `55ef0a75-f261-47e9-a72b-f5c61c32d339`). Generally, immutable server-assigned UUIDs are used in production environments. | ### Retrieve the IDs of all managed users in the repository ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user?_queryFilter=true&_fields=_id" { "result": [ { "_id": "bjensen", "_rev": "0000000079b78ace" }, { "_id": "scarter", "_rev": "0000000070e587a7" }, ... ], ... } ``` ### Query managed users for a specific user The `_queryFilter` requires double quotes, or the URL-encoded equivalent (`%22`), around the search term. This example uses the URL-encoded equivalent: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+%22scarter%22" { "result": [ { "_id": "scarter", "_rev": "0000000070e587a7", "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 "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ 'http://localhost:8080/openidm/managed/user?_queryFilter=userName+eq+"scarter"' { "result": [ { "_id": "scarter", "_rev": "0000000070e587a7", "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 ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/scarter" { "_id": "scarter", "_rev": "0000000070e587a7", "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 ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --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" }' \ "http://localhost:8080/openidm/managed/user/bjackson" { "_id": "bjackson", "_rev": "0000000055c185c5", "userName": "bjackson", "sn": "Jackson", "givenName": "Barbara", "mail": "bjackson@example.com", "telephoneNumber": "082082082", "accountStatus": "active", "effectiveAssignments": [], "effectiveRoles": [] } ``` ### Add a user with a system-generated ID ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "userName": "pjensen", "sn": "Jensen", "givenName": "Pam", "mail": "pjensen@example.com", "telephoneNumber": "082082082", "password": "Passw0rd" }' \ "http://localhost:8080/openidm/managed/user?_action=create" { "_id": "9d92cdc8-8b22-4037-a344-df960ea66194", "_rev": "00000000a4bf9006", "userName": "pjensen", "sn": "Jensen", "givenName": "Pam", "mail": "pjensen@example.com", "telephoneNumber": "082082082", "accountStatus": "active", "effectiveAssignments": [], "effectiveRoles": [] } ``` ### Update a user This example checks whether user `bjensen` exists, then replaces her telephone number with the new data provided in the request body: ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '[ { "operation": "replace", "field": "/telephoneNumber", "value": "0763483726" } ]' \ "http://localhost:8080/openidm/managed/user?_action=patch&_queryFilter=userName+eq+'bjackson'" { "userName": "bjackson", "sn": "Jackson", "givenName": "Barbara", "mail": "bjackson@example.com", "telephoneNumber": "0763483726", "accountStatus": "active", "effectiveAssignments": [], "effectiveRoles": [], "_rev": "000000008c0f8617", "_id": "bjackson" } ``` ### Delete a user ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request DELETE \ "http://localhost:8080/openidm/managed/user/bjackson" { "_id": "bjackson", "_rev": "000000008c0f8617", "userName": "bjackson", "sn": "Jackson", "givenName": "Barbara", "mail": "bjackson@example.com", "telephoneNumber": "0763483726", "accountStatus": "active", "effectiveAssignments": [], "effectiveRoles": [] } ```