REST API calls fail after upgrading to OpenAM 13.x

Last updated Jan 5, 2021

The purpose of this article is to provide assistance if your REST API calls (that worked previously) fail after upgrading to OpenAM 13.x. This includes requests made indirectly; for example, when you create a REST STS instance in the OpenAM console.

1 reader recommends this article


This article has been archived and is no longer maintained by ForgeRock.


The REST call, or OpenAM functionality that has an underlying REST request, fails after upgrading to OpenAM 13.x. The same behavior worked in older versions.

Example failed request 

The following example shows a REST call and the possible failed responses:

$ curl --request POST --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --header "Content-Type: application/json" --data '{"currentpassword":"changeit","userpassword":"newpassword"}'

Which can result in:

{"code":501,"reason":"Not Implemented","message":"Actions are not supported for resource instances"}


{"code":404,"reason":"Not Found","message":"User not found"}

Example failed functionality with underlying REST request

When adding a REST STS instance in the OpenAM console, you may receive the following error:

HTTP Status 500 - AMSetupFilter.doFilter

Recent Changes

Upgraded to OpenAM 13.x.


The resource version associated with the REST request is incompatible with the endpoint being called and OpenAM release combination.  

REST API features have version numbers to allow for compatibility between releases. The version number of a feature increases when a non-backwards-compatible change is introduced that affects clients making use of the feature. Versioning is provided for the resource and protocol elements. See OpenAM Developer's Guide › REST API Versioning for further information on versioning.

OpenAM supports protocol version 1.0; supported resource versions vary according to the endpoint and the release you are using. You should check Supported resource Versions for further information.


This issue can be resolved by ensuring you use a resource version that is appropriate to the endpoint and OpenAM release you are using.

You can configure a global setting to determine version compatibility or specify the versions in your REST request.

Global setting

You can configure the global setting using either the OpenAM console or ssoadm:

  • OpenAM 13.5 console: navigate to: Configure > Global Services > REST APIs > Default Version and select the appropriate option. 
  • OpenAM 13 console: navigate to: Configuration > Global > REST APIs > Default Version and select the appropriate option. 
  • ssoadm: enter the following command: $ ./ssoadm set-attr-defs -s RestApisService -t Global -u [adminID] -f [passwordfile] -a openam-rest-apis-default-version=[version] replacing [adminID], [passwordfile] and [version] with appropriate values, where [version] is LATEST, OLDEST or NONE.

The options available are:

  • LATEST: The latest available supported version of the API is used. This is the preset default for new installations of OpenAM.
  • OLDEST: The oldest available supported version of the API is used. This is the preset default for upgraded OpenAM instances.
  • NONE: If a version is not specified in the request, it will not be defaulted. 

If you select NONE for the global setting, you must always specify the version in the REST request. If the version is not specified the request will not be handled and will result in a 400 Bad Request error.

You can include the Accept-API-Version header in your REST call to specify the versions. For example, to include resource version 2.0 you would include the following header:

"Accept-API-Version: resource=2.0"

For example:

$ curl --request POST --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --header "Accept-API-Version: resource=2.0" --header "Content-Type: application/json" --data '{"currentpassword":"changeit", "userpassword":"newpassword"}'

 See OpenAM Developer's Guide › Specifying an Explicit REST API Version for further information.

See Also


OpenAM Developer's Guide › REST API Versioning

OpenAM Administration Guide › Configuring REST APIs

Related Training


Related Issue Tracker IDs


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