ForgeRock Blog

ForgeRock Common REST API Overview

One of the unique features of the ForgeRock Open Identity Stack is that all components of the stack share a single, easy-to-use RESTful web API. REST stands for Representational State Transfer and is a technique that relies on stateless, client-server and cacheable communication where the HTTP protocol is used. Not only is REST a more lightweight alternative to traditional SOAP-based web services, but given its HTTP nature, it is easy to use in a firewall-controlled environment.

The Open Identity Stack contains three different products, each with individual modules and capabilities: OpenAM, OpenDJ, and OpenIDM. The Common REST or CREST can be used to access and leverage all the underlying modules and features with a set of easy-to-remember REST calls (CRUDPAQ).


Add a resource that does not yet exist


Modify part of an existing resource


Retrieve a single resource


Perform a predefined action


Replace an existing resource


List a set of resources


Remove an existing resource



OpenAM offers a RESTful API for authentication, logout, cookie information, token attribute retrieval and token validation, authorization, OAuth 2.0 Authorization, OpenID Connect 1.0, self-registration, password management, managing identities, managing realms, and logging.


The present implementation in OpenDJ maps JSON resources onto LDAP entries, meaning REST clients can in principle do just about anything an LDAP client can do with directory data.


OpenIDM provides an implementation that allows you to manipulate managed objects as well as system objects.


Interacting with the RESTful API

There are a number of ways and programming languages with which you can easily interact with the ForgeRock Common REST API. An easy way to invoke REST calls is to get a hold of a REST client that allows you to easily provide the necessary details, save calls, and tweak them as you play with the interface. One REST client that we often refer to in our documentation is CURL ( CURL is a command line tool for submitting data with URL syntax and is free to use.


Some examples using ForgeRock Common REST

Let’s retrieve a user from OpenDJ, authenticated as Stevie with password Wonder.

$ curl

–request GET

–user stevie:wonder


 “_rev” : “000000005b337348”,

 “schemas” : [ “urn:scim:schemas:core:1.0” ],

 “contactInformation” : {

   “telephoneNumber” : “+1 408 555 1212”,

   “emailAddress” : “”


 “_id” : “newuser”,

 “name” : {

   “familyName” : “New”,

   “givenName” : “User”


 “userName” : “”,

 “displayName” : “New User”,

 “meta” : {

   “created” : “2013-04-11T09:58:27Z”


 “manager” : [ {

   “_id” : “kvaughan”,

   “displayName” : “Olivia Pope”

 } ]



In OpenIDM we can simply create a new user using

$ curl –header “Content-Type: application/json”

–header “X-OpenIDM-Username: openidm-admin”

–header “X-OpenIDM-Password: openidm-admin”

–request PUT –data ‘{ “userName”:”joe”, “givenName”:”joe”, “familyName”:”smith”, “email”:””, “phoneNumber”:”555-123-1234″, “password”:”TestPassw0rd”, “description”:”My first user” }’ http://localhost:8080/openidm/managed/user/joe

In OpenAM we can perform an authentication with the following call:

$ curl –request POST

–header “X-OpenAM-Username: demo” –header “X-OpenAM-Password: changeit”

–header “Content-Type: application/json” –data “{}”

{ “tokenId”: “AQIC5w…NTcy*”, “successUrl”: “/openam/console” }

The above are just three simple calls to showcase the ease of use and flexibility of the Common REST API the Open Identity Stack offers. Check out the suggested reading links for more examples and information on how to leverage the capabilities exposed by the API.


Suggested reading