ForgeRock REST is a REST API framework defining common APIs to access web resources and collections of resources.
Endpoints generally return JSON-format resources, though resource formats can depend on the implementation.
Resources in collections can be found by their unique identifiers (IDs).
IDs are exposed in the resource URIs.
For example, if a service has a user collection under
/users, you can access a user at
The ID is also the value of the
_id field of the resource.
Resources are versioned using revision numbers.
A revision is specified in the resource’s
Revisions make it possible to figure out whether to apply changes
without resource locking and without distributed transactions.
The ForgeRock REST APIs use the following verbs, sometimes referred to collectively as CRUDPAQ. For details and HTTP-based examples of each, follow the links to the sections for each verb.
Add a new resource with HTTP PUT or HTTP POST.
Retrieve a single resource with HTTP GET.
Replace an existing resource with HTTP PUT.
Remove an existing resource with HTTP DELETE.
Modify part of an existing resource with HTTP PATCH.
Perform a predefined action with HTTP POST.
Search a collection of resources with HTTP GET.
ForgeRock REST reserved query string parameter names start with an underscore (
Reserved query string parameters include, but are not limited to, the following names:
|Some parameter values are not safe for URLs; URL-encode parameter values as necessary.|
The action verb is the main vehicle for extensions.
For example, to create a new user with HTTP POST rather than HTTP PUT, you might use
An endpoint can define additional actions.
A service can define stored queries to call by ID.
Stored queries can call for additional parameters.
The parameters are also passed in the query string.
Which parameters are valid depends on the stored query.