ForgeRock Identity Platform
Does not apply to Identity Cloud


Last updated Jul 7, 2022

The purpose of this FAQ is to provide answers to commonly asked questions regarding the REST API in DS.

Frequently asked questions

Q. Can I do a negation query with the REST API?

A. Yes, you can using the boolean operator ! (not). Examples of queries that can be performed via REST (with the equivalent LDAP filter for comparison) are shown in Query

Q. Can I trace what is happening when a REST call is made for troubleshooting purposes?

A. Yes, if you are using the HTTP connection handler, you can enable logging for the REST interface and the REST to LDAP (REST2LDAP) gateway servlet if it runs in the Apache Tomcat™ web container. See How do I troubleshoot a DS (All versions) REST configuration? for further information.

Q. Can I create password policies at the system level using the REST API?

A. Yes you can add and edit password policy definitions at the system level using REST (over the /admin/config endpoint) provided you have created the necessary mapping details in the API Configuration. See Subentry Password Policies for an example.


It is not possible to assign a password policy to specific users or groups using REST, nor to see and manage a user's password state (that is, locked, reset, etc.).

Q. Are there any REST endpoints in DS for creating organizational units and organizations?

A. Endpoints in the DS REST API can be configured to allow the creation of any type of entry in the DS DIT.

It is possible to define relationships between resources using SubResources, meaning entries can be created at different levels beneath the base DN. You can configure mapping details for a resource in the mapping configuration file to allow organizational units and organizations to be created; these resource details should be similar to the existing users resource, which allows you to create person objects below ou=People,dc=example,dc=com. See REST to LDAP Reference for further information.

Q. Can I define mappings/resources using search scopes and filters in the same way as for LDAP searches?

A. No, the way mappings/resources are defined in the REST API is not directly equivalent to LDAP searches. The concept of a subtree scope for searches does not relate to mappings as the server needs to be able to compute base DNs based on the REST resources. The concept of a subtree search does not fit this model. For example, if a CREATE operation was issued, the server would not know where to write the new entry in the tree. Each mapping needs to be definable in a way that you can map the REST resource to base DN and vice versa in a strictly defined way; this is done using namingStrategy in the REST API.

See REST to LDAP Reference for further information on namingStrategy.

You cannot use filters for defining the collections included in the mappings. However, you can run filters when using the REST interface by including them in a QUERY.

Q. Does the REST API support user names and identifiers that contain *?

A. Yes, the REST API in DS does work with user names and identifiers containing *. However, there is a serious risk that LDAP client applications may not escape the * character when using it in String representation of LDAP search filters, which will result in heavy, resource consuming requests in the directory.


It is recommended that you avoid using * (and other special characters) in your user names and identifiers to avoid any potential issues.

Q. Can I use cn=Directory Manager for creating new entries (pre-DS 7)?

A. You cannot easily do this if you use the HTTP connection handler nor is it recommended.

If you use the REST2LDAP gateway servlet, you can achieve this by setting the bind to simple under authorization > basic to allow you to pick specific bind DNs.

However, best practice is to create a separate administrative user under the base DN who has the necessary access controls (ACIs) for creating the required entries. See Managing Administrator Accounts for further information.

See Also

How do I troubleshoot a DS (All versions) REST configuration?

HTTP Access


Access Control

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.