ForgeRock Identity Platform
ForgeRock Identity Cloud

URLDecoder: Illegal hex characters in escape (%) pattern or Client authentication failed error when requesting an OAuth2 access token in Identity Cloud or AM (All versions)

Last updated Jan 16, 2023

The purpose of this article is to provide assistance if you receive a "URLDecoder: Illegal hex characters in escape (%) pattern" or "Client authentication failed" response when making a call to the OAuth2 access_token endpoint in ForgeRock Identity Cloud or AM using a basic authorization header. You may see this in Identity Cloud; AM 6.5 and later when the client ID and secret are not URL encoded, or in earlier versions when one or both of them are URL encoded.


One of the following responses is received when requesting a token from the access_token endpoint using a basic authorization header:

  • invalid_request: { "error_description": "URLDecoder: Illegal hex characters in escape (%) pattern - For input string: \"+\"", "error": "invalid_request" }
  • invalid_client: { "error_description": "Client authentication failed", "error": "invalid_client" }

You may see an error similar to the following in the AM Authentication debug log when this happens:

Invalid Password : failedUserId clientID amAuth:10/09/2019 04:09:56:646 PM BST: Thread[http-bio-8080-exec-2,5,main]: TransactionId[af1f9187-1d99-4240-8208-7db8bd3cb128-86180] Invalid Password : Exception com.sun.identity.authentication.spi.InvalidPasswordException: invalid password at com.sun.identity.idm.plugins.internal.AgentsRepo.authenticate( ...

Recent Changes

Deployed Identity Cloud.

Upgraded to AM 6.5 or later.

URL encoded special characters in the client ID and/or secret in the basic authorization header in AM 6.


Changes were made in AM 6.5 to allow the client ID and secret to be URL encoded when using the basic authorization header per the standard (RFC 6749). This also applies to Identity Cloud.

You will see this error in different versions as follows:

  • Identity Cloud; AM 6.5 and later: this error signifies that one or both of the client ID and secret are not URL encoded. Any special characters in both the client ID and secret must be URL encoded.
  • AM 6: this error indicates that the client ID and/or secret are URL encoded (which is not supported in earlier versions).


This issue can be resolved as follows depending on your version:

  • Identity Cloud; AM 6.5 and later

You should URL encode (UTF-8) any special characters in the client ID and secret before base64 encoding the string for the basic authorization header. Refer to the example process in Authenticate to AM over REST for further information.

Alternatively, you should remove any special characters from the client ID and secret.

See FAQ: OAuth 2.0 in Identity Cloud and AM (Q. Why don't all special characters in client IDs and secrets need URL encoding?) for further information on which special characters do need URL encoding.

  • AM 6

You should upgrade to AM 6.5 or later, which supports URL encoded client IDs and secrets; you can download this from Backstage. Alternatively, you can remove any URL encoding from the client ID and secret.

See Also

OAuth 2.0 and OIDC in AM

Authenticate clients with authorization headers

Related Training


Related Issue Tracker IDs

OPENAM-15454 (Section on Basic Auth on OAuth2 guide should mention URL encoding)

OPENAM-14306 (OAuth2 client secret - not all special characters require encoding)

OPENAM-13609 (Allow for URL encoded client id and secret in basic auth secured oauth endpoints)

OPENAM-11360 (OAuth2 ClientID and password URL decoded as per RFC-6749 )

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