FAQ
ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: REST API in AM

Last updated Apr 13, 2021

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


2 readers recommend this article

Frequently asked questions

Note

Please observe the following when constructing REST calls:

  • Make the REST call to the actual AM server URL (not lb).
  • Change the name of the iPlanetDirectoryPro header to the name of your actual session cookie.
  • Set this session cookie header to the token returned when you authenticated.
  • Ensure the Accept-API-Version header contains valid resource versions.

See How do I avoid common issues with REST calls in AM (All versions)? for further information.

Microsoft® Windows®

If you are using Microsoft Windows, you should be aware that & is treated as a special character. If it is included in a URL, you should either put the URL in quotes or escape the & using ^&. For example, to authenticate to the LDAP module, you could do one of the following:

$ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" "http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=module&authIndexValue=LDAP" $ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate?authIndexType=module^&authIndexValue=LDAP

Q. How can I access the REST APIs?

A. The REST APIs are built on the same underlying CRUDPAQ model that is used in DS and IDM.

You can access the REST APIs under /json where you deployed AM, for example: http://host1.example.com:8080/openam/json

See How do I update REST API calls after upgrading to a newer version of AM? for a single point of reference for evolving REST endpoints.

Q. What is the correct format of the URL for specifying realms in a REST call?

A. To specify a realm in a rest call, you should insert the realm name just before the endpoint. For example:http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/authenticate

This is detailed in Getting Started with REST › Specifying Realms in REST API Calls along with other options.

Q. Does a user need to be an admin user to use the REST API?

A. No, any user can use the REST API providing they authenticate first. Upon authenticating, they will receive a valid token, which can be used to access many REST endpoints. However, requests to the /json/sessions endpoint must be done by the amAdmin user. See How do I validate session tokens and obtain session details using the REST API in AM (All versions)? and Getting Started with REST › Introducing REST in AM for further information.

If you want an administrator to perform certain tasks within REST, such as configuring policies, you can set up delegated administration as described in How do I add privileges to identity groups in AM (All versions)? and Security Guide › Delegating Privileges.

Q. Is there a way to check if a token is valid over REST?

A. Yes, you can perform a POST request to the sessions endpoint using the validate action to check if a token is valid, where the tokenId value is the token of the session you are validating. For example:

  • AM 5.5 and later: $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.1" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" -d '{"tokenId" : "BXCCq...NX*1*"}' http://host1.example.com:8080/openam/json/realms/root/sessions?_action=validate
  • AM 5 and 5.1.x: $ curl -X POST -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" "http://host1.example.com:8080/openam/json/realms/root/sessions?_action=validate&tokenId=BXCCq...NX*1*"

Example response:

{    "valid": true,     "sessionUid": "d115c3ab-ea09-48b3-b406-0da91df8f525-36068",     "uid": "demo",     "realm": "/" }

Q. Can I retrieve total number of active sessions at a given point in time from AM using the REST API?

A. Yes, you can use a REST call to get session information, as demonstrated in the following example:

$ curl -X GET -H "iPlanetDirectoryPro:AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/json/realms/root/sessions?_queryID=all
Note

The maximum number of sessions returned by this interface is 120.

Q. How can I check session details using REST?

A. You can check session details (such as the remaining session time and the idle session time) using the /json/sessions endpoint. You can also use this endpoint to validate session tokens.

See How do I validate session tokens and obtain session details using the REST API in AM (All versions)? for further information.

Q. Can I query protected session properties using the REST API?

A. Yes, protected session properties can be read via the REST API; you must add the session property to the Session Property Whitelist first to allow it to be read. See Reference › Session Property Whitelist Service for further information.

Protected session properties are any that have the am.protected prefix or any of the following:

  • HOST
  • HOST_NAME
  • AuthLevel
  • AuthType
  • Principal
  • UserId
  • UserToken
  • Organization
  • cookieSupport
  • authInstant
  • Principals
  • loginURL
  • FullLoginURL
  • Role
  • Service
  • SessionTimedOut
  • SESSION_HANDLE_PROP
  • TOKEN_RESTRICTION_PROP
  • AM_MAX_IDLE_TIME
  • AM_MAX_SESSION_TIME
  • Constants.AM_CTX_ID
  • Constants.UNIVERSAL_IDENTIFIER

You can read them using the getSessionInfo or getProperty action (depending on version) as demonstrated for AuthLevel in How do I validate session tokens and obtain session details using the REST API in AM (All versions)? (Checking the authentication level) and for other protected properties in How do I retrieve user attributes from a session using the REST API in AM (All versions)?

Note

You cannot set or delete these session properties via REST.

Q. How can I use a query to return selected users?

A. You can use the _queryFilter parameter. For example, to return the demo user:

$ curl -X GET -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0,protocol=1.0" -H "iPlanetDirectoryPro:AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --data-urlencode '_queryFilter=uid eq "demo"' http://host1.example.com:8080/openam/json/realms/root/users

See Getting Started with REST › Query for further information.

Q. How can I get the properties for a user in a realm using the REST API?

A. You can use the following REST call to retrieve properties for a user in a realm, where the iPlanetDirectoryPro cookie value is the one returned when you successfully authenticated and myRealm is the name of your realm:

$ curl -X GET -H "Content-Type: application/json" -H "Accept-API-Version: resource=3.0,protocol=1.0" -H "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/users/demo

Q. How can I update a user attribute with a blank value?

You can update a user attribute with a blank value or remove the value for an existing attribute by setting the value to []. For example, to remove the current value for the mail attribute, you would specify the following in the data element of your REST call:

{"mail": []}

Q. Can I specify the tree, module or chain to use for authentication in a REST call?

A. Yes, you can by making use of the authIndexType and authIndexValue parameters. For example:

  • To authenticate using a specific tree: http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/authenticate?authIndexType=service&authIndexValue=authTree
  • To authenticate using a specific chain: http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/authenticate?authIndexType=service&authIndexValue=authChain
  • To authenticate using a specific module: http://host1.example.com:8080/openam/json/realms/root/realms/myRealm/authenticate?authIndexType=module&authIndexValue=moduleName

See Getting Started with REST › Authenticating to AM Using REST for further information on these parameters.

Q. Can I create a realm using the REST API?

A. Yes, you can create a realm using the REST API, but it will not work until you also create the associated services because these are not created when a realm is created via REST. It is recommended that you create a realm using either the console or ssoadm.

See Setup Guide › Realms for further information.

Q. Can I configure agents using the REST API?

A. Yes, you can add and update agent profiles using the REST API as detailed in How do I create and update an Agent in AM (All versions) using the REST API? This article also provides a Postman collection to make it easier to create and update agents.

See Setup Guide › Creating Identities for further information; most of the examples are for identities but also work for other objects such as agent profiles.

Q. How do I create groups using the REST API?

A. You can use POST or PUT requests to create a variety of objects including groups. There are examples in Setup Guide › Creating Identities for creating a group called newGroup using a POST request and a group called anotherGroup using a PUT request.

Q. Does AM support REST-STS?

A. Yes the RESTful Security Token Service (REST-STS) is supported in AM.

See the following articles and documentation links for further information:

Q. How can I protect a REST endpoint?

A. You can protect a REST endpoint using one of the following approaches:

  • Use IG to protect the REST endpoint. To achieve this, AM acts as an OAuth2 authorization server and IG acts as a resource server. IG can then verify that requests to the REST API contain a valid Access token that has been issued by AM. See Gateway Guide › Acting As an OAuth 2.0 Resource Server for further information.
  • Put a Java Servlet Filter in front of the REST endpoint.
  • Provide another endpoint that acts as a proxy, meaning the flow would be as follows: User -> REST -> proxyEndpoint (which does the filtering ) -> REST -> actualEndpoint

Q. How can I authenticate over REST and get a tokenID using zero page login?

A. You can achieve this by passing the username in a X-OpenAM-Username header and the password in a X-OpenAM-Password header as demonstrated in the example below:

$ curl -X POST -H "X-OpenAM-Username: demo" -H "X-OpenAM-Password: changeit" -H "Content-Type: application/json" -H "Accept-API-Version: resource=2.1" http://host1.example.com:8080/openam/json/realms/root/authenticate

Example response:

{ "tokenId": "AQIC5wM2LY4SfcyPCKVhaca6lRav2ZgOyGf8KWmyDdu80tc.*AAJTSQACMDIAAlNLABQtMjIyNDg0MTYzNTQ3ODg2NzI1MwACUzEAAjAx*", "successUrl": "/openam/console", "realm": "/" }

The response you receive shows the tokenId that corresponds to the user session. The successUrl is the URI to which the user would normally be redirected.

Note

"zero page login" mechanism works only for name/password authentication. More examples can be found in the Getting Started with REST › Authenticating to AM Using REST

See Also

How do I create a policy in AM (All versions) using the REST API?

How do I change a user's password using the REST API in AM (All versions)?

How do I retrieve user attributes from a session using the REST API in AM (All versions)?

How do I force REST API responses to always use lower case for attribute names in AM (All versions)?

Using the REST API in AM

Getting Started with REST › Introducing REST in AM

Related Training

ForgeRock Access Management Core Concepts (AM-400)


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