Getting started with the ForgeRock Identity Cloud REST API: Part 1 - Introduction

This is Part 1 of 8 in the series Getting started with the ForgeRock Identity Cloud REST API.

Introduction to REST APIs in Identity Cloud ~ 5 min

ForgeRock Identity Cloud is a ForgeRock managed Identity and Access Management solution hosted on Google Cloud Platform (GCP), with unmatched security architecture built for Enterprise.

REST stands for Representational State Transfer. As an architectural style for building web services, it uses the HTTP protocol to enable communication between systems. In a RESTful architecture, each resource is represented by a Uniform Resource Identifier (URI), and the resource can be operated on by sending various HTTP requests (GET, POST, PUT, DELETE etc.) to the URI.

Identity Cloud has published HTTP endpoints for various functionalities. REST clients can invoke HTTP calls to the Identity Cloud REST APIs to use its various functionalities.

As an example, for a quick health check of an Identity Cloud tenant, use a REST client to invoke HTTP request to its publicly accessible endpoint “/monitoring/health” as shown below.


$ curl --request GET 'https://<id-cloud-tenant>/monitoring/health'


  "status": "OK"

The “/monitoring/health” HTTP endpoint does not require authentication, but other Identity Cloud REST APIs requests require either an access token or Log API keys.

About this guide

This is Part 1 of 8 in a series of articles that make up the Getting Started guide for using the REST API with Identity Cloud. The other guides in the series are:

The guides walk through most of the use cases made available in the Identity Cloud Postman Collection. Wherever feasible, the command line equivalent of REST requests and their responses are included for reference.

The screenshots of the Postman interface (version 10.13.4) used throughout the guide are from a Mac OS X version. While it shouldn’t look/behave too differently in other Operating Systems, some steps in the guide might require minor adaptations depending on the Operating System type and/or Postman version.

The guide uses curl for REST API examples and jq for formatting the JSON responses, and Postman. Install these applications on your local if you haven’t already.

NOTE: The guide assumes its readers have administrative access to an Identity Cloud tenant.

About the ForgeRock Identity Cloud Postman collection

Examples of REST APIs used for common tasks in Identity Cloud such as user management, authentication, and authorization are grouped in a Postman collection.

Different components are responsible for various functionalities of Identity Cloud. Authentication and authorization in Identity Cloud are handled by the Access Management (AM) component, User Management is handled by Identity Management (IDM). When working on the Postman Collections, notice the presence of “/am” or “/openidm” in some of the HTTP endpoints.

To understand the Identity Cloud Rest API, it is a good practice to study the method, parameters (params), headers, body and the URI of each HTTP request example.

An Identity Cloud tenant has two realms namely alpha and bravo. A realm is a basic unit of administration in an Identity Cloud tenant. Each realm can have its own set of Identities to manage, authentication journeys, password policies, etc. The Postman Collection examples operate on the alpha realm of the Identity Cloud tenant. By changing the realm name in HTTP endpoints, the examples can be made to work on the Bravo realm as well.

Preparing the ForgeRock Identity Cloud Postman collection environment ~ 5min

  1. Download the Identity Cloud Postman collection from the ForgeRock Identity Cloud official documentation.

  2. In Postman, open your workspace and click Import.

  3. Paste the URL for ForgeRock Identity Cloud Postman Collection.

  4. Click > on the left side of the Collection name to expand various groups.

    Each group expands to show example REST calls that consume functionalities exposed by various Identity Cloud REST endpoints. For example, the Intelligent Access folder groups REST calls to authenticate a user with Identity Cloud, get the user’s session details etc.

  5. To start using the ForgeRock Identity Cloud Postman Collection, create a user in Identity Cloud:

    a. In a supported browser, log into your Identity Cloud Admin UI.

    b. In the alpha realm, go to Identities > Manage > + New Alpha realm - User.

  6. Create a new Identity Cloud user using the following information:

  7. On the postmanAdminUser edit profile page, click on Authorization Roles > + Add Authorization Roles.

  8. Add the following Authorization Roles and click Save.

    • openidm-authorized
    • openidm-admin
  9. In Postman, go to ForgeRock Identity Cloud Collection > Variables. See Variables for further information.

  10. Change the current values for the variables in the table below to reflect the Identity Cloud environment specific details. For example, replace the value of the PlatformUrl variable from <tenant-env-fqdn> to the Identity Cloud tenant URL being used.

    To get the cookieName of your Identity Cloud tenant, log in to the Identity Cloud Admin UI, click on Tenant settings on the top right corner of the administrator dashboard and look for Global settings > Cookie.

platformUrl Replace <tenant-env-fqdn> with Identity Cloud tenant URL
amUrl Replace <tenant-env-fqdn> section with Identity Cloud tenant URL
idmUrl Replace <tenant-env-fqdn> section with Identity Cloud tenant URL
IDCloudAdminUsername Identity Cloud tenant administrator
IDCloudAdminPassword Identity Cloud tenant administrator password
cookieName cookieName in your ForgeRock Identity Cloud Tenant settings.
postmanClientSecret postmanClientSecret
postmanAdminUsername postmanAdminUser
postmanAdminPassword Rock5tar10$
postmanDemoPassword p0stmanD3moPas$word

  1. Click Save.

The environment is now ready to run the ForgeRock Identity Cloud Postman Collection.

Further reading

Other guides in the Getting started with the ForgeRock Identity Cloud REST API series:

Other useful links: