--- title: Interact with IDM description: There are two primary ways to interact with IDM; programmatically, using REST to access IDM's API endpoints, or using the browser-based user interfaces. component: pingidm version: 8.1 page_id: pingidm:install-guide:interact-with-idm canonical_url: https://docs.pingidentity.com/pingidm/8.1/install-guide/interact-with-idm.html keywords: ["Installation", "REST", "User Interfaces"] section_ids: first-steps-with-rest: REST interface introduction rest-output-format: Format REST output for readability openidm-uis: IDM user interfaces --- # Interact with IDM There are two primary ways to interact with IDM; programmatically, using REST to access IDM's API endpoints, or using the browser-based user interfaces. ## REST interface introduction IDM provides RESTful access to users in its repository, and to its configuration. To access the repository over REST, you can use a browser-based REST client, such as the *Simple REST Client* for Chrome, or *RESTClient* for Firefox. You can also use applications such as *Postman* to create, run, and manage collections of REST calls. Alternatively you can use the `curl` command-line utility, included with most operating systems. For more information about `curl`, refer to . IDM is accessible over the regular and secure HTTP ports of the Jetty Servlet container, 8080, and 8443. Most of the command-line examples in this documentation set use the regular HTTP port, so that you don't have to use certificates just to test IDM. In a production deployment, install a CA-signed certificate and restrict REST access to a secure (HTTPS) port. To run `curl` over the secure port, 8443, you must either include the `--insecure` option, or follow the instructions in [Restrict REST Access to the HTTPS Port](../security-guide/chap-connections.html#security-https). You can use those instructions with the self-signed certificate that is generated when IDM starts, or with a `*.crt` file provided by a certificate authority. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Some of the examples in this documentation set 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. | > **Collapse: Try Out IDM Using REST** > > 1. Use the following REST query to list all users in the IDM 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" > ``` > > When you first install IDM with an empty repository, no users exist. > > 2. Create a user `joe` by sending a RESTful POST. > > The following `curl` command creates a managed user in the repository, and set the user's ID to `jdoe`: > > * Bash > > * PowerShell > > ``` > 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": "joe", > "givenName": "joe", > "sn": "smith", > "mail": "joe@example.com", > "telephoneNumber": "555-123-1234", > "password": "TestPassw0rd", > "description": "My first user", > "_id": "joe" > }' \ > http://localhost:8080/openidm/managed/user?_action=create > { > "_id": "joe", > "_rev": "00000000c03fd7aa", > "userName": "joe", > "givenName": "joe", > "sn": "smith", > "mail": "joe@example.com", > "telephoneNumber": "555-123-1234", > "description": "My first user", > "accountStatus": "active", > "effectiveRoles": [], > "effectiveAssignments": [] > } > ``` > > ``` > 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": "joe", > "givenName": "joe", > "sn": "smith", > "mail": "joe@example.com", > "telephoneNumber": "555-123-1234", > "password": "TestPassw0rd", > "description": "My first user", > "_id": "joe" > }' ` > http://localhost:8080/openidm/managed/user?_action=create > { > "_id": "joe", > "_rev": "00000000c03fd7aa", > "userName": "joe", > "givenName": "joe", > "sn": "smith", > "mail": "joe@example.com", > "telephoneNumber": "555-123-1234", > "description": "My first user", > "accountStatus": "active", > "effectiveRoles": [], > "effectiveAssignments": [] > } > ``` > > 3. Fetch the newly created user from the repository with a RESTful GET: > > * Bash > > * PowerShell > > ``` > 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/joe > { > "_id": "joe", > "_rev": "00000000c03fd7aa", > "userName": "joe", > "givenName": "joe", > "sn": "smith", > "mail": "joe@example.com", > "telephoneNumber": "555-123-1234", > "description": "My first user", > "accountStatus": "active", > "effectiveRoles": [], > "effectiveAssignments": [] > } > ``` > > ``` > 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/joe > { > "_id": "joe", > "_rev": "00000000c03fd7aa", > "userName": "joe", > "givenName": "joe", > "sn": "smith", > "mail": "joe@example.com", > "telephoneNumber": "555-123-1234", > "description": "My first user", > "accountStatus": "active", > "effectiveRoles": [], > "effectiveAssignments": [] > } > ``` ### Format REST output for readability By default, `curl`-based REST calls return the JSON object on one line, which can be difficult to read. For example: ``` {"mail":"joe@example.com","sn":"smith","passwordAttempts":"0", "lastPasswordAttempt":"Mon Apr 14 2014 11:13:37 GMT-0800 (GMT-08:00)", "givenName":"joe","effectiveRoles":["internal/role/openidm-authorized"], "password":{"$crypto":{"type":"x-simple-encryption","value":{"data": "OBFVL9cG8uaLoo1N+SMJ3g==","cipher":"AES/CBC/PKCS5Padding","iv": "7rlV4EwkwdRHkt19F8g22A==","key":"openidm-sym-default"}}},"country":"", "city":"","_rev": "00000000c03fd7aa","lastPasswordSet":"","postalCode":"", "_id":"joe3","description":"My first user","accountStatus":"active","telephoneNumber": "555-123-1234","roles":["internal/role/openidm-authorized"],"effectiveAssignments":{}, "postalAddress":"","stateProvince":"","userName":"joe3"} ``` At least two options are available to clean up this output: > **Collapse: Format Output Using a JSON Parser** > > The standard way to format JSON output is with a JSON parser such as [jq](http://stedolan.github.io/jq/). `jq` is not installed by default on most operating systems, but you can install it and then "pipe" the output of a REST call to `jq`, as follows: > > ``` > 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/joe" \ > | jq . > ``` > **Collapse: Format Output Using the REST API** > > The Ping REST API includes an optional `_prettyPrint` request parameter. The default value is `false`. To use the REST API to format output, add a parameter such as `?_prettyPrint=true` or `&_prettyPrint=true`, depending on whether it is added to the end of an existing request parameter. In this case, the following command would return formatted output: > > ``` > 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/joe?_prettyPrint=true" > ``` > > | | | > | - | ----------------------------------------------------------------------------------------------------------------- | > | | Most command-line examples in this guide do not show this parameter, but the output is formatted for readability. | ## IDM user interfaces IDM has two types of user interfaces, an administrative UI for managing the IDM deployment and an end-user UI for letting end users manage certain aspects of their own accounts. These UIs aren't bundled with IDM. You can download and install each separately from the [Backstage download site](https://backstage.forgerock.com/downloads). * Administrative UI You have two options for the administrative UI: * The [Platform admin UI](../setup-guide/platform-admin-ui.html) is the replacement for the legacy admin UI and is the recommended option for new deployments. Deploy it behind a standalone Nginx server or as a Docker container. * The [legacy admin UI](../setup-guide/legacy-admin-ui.html) is deprecated, but remains available for customers who still depend on it. * End-user UI The [IDM end-user UI](../setup-guide/idm-enduser-ui.html) provides role-based access to specific tasks and allows users to manage certain aspects of their own accounts. Learn more in [User interfaces](../setup-guide/chap-ui.html).