URL Encoding Issue in Azure API Management - Encoded Forward Slash (%2F) Getting Decoded Automatically

Question

URL Encoding Issue in Azure API Management - Encoded Forward Slash (%2F) Getting Decoded Automatically

Rishav Arora 20

Description:

We are experiencing a URL encoding issue with Azure API Management where encoded forward slashes (%2F) in URL paths are being automatically decoded, causing routing problems.

Issue Details:

Expected Behavior:

Frontend sends request to: https://{base_url}/item/sb180d5e-ad82c28dc05b_12%2F27
API Management should preserve the encoded format and pass the same URL structure to the backend

Actual Behavior:

Frontend sends: https://{base_url}/item/sb180d5e-ad82c28dc05b_12%2F27
API Management automatically decodes %2F to / resulting in: https://{base_url}/item/sb180d5e-ad82c28dc05b_12/27
This creates incorrect path interpretation and routing failures

Impact:

API calls fail due to incorrect path resolution
Backend services cannot properly identify the intended resource
URL parameters containing encoded forward slashes are not handled correctly

Environment:

Azure API Management (Consumption tier)
Frontend: (React)

Questions:

Is there a configuration setting in APIM to preserve URL encoding for path parameters?
Are there any policies that can prevent automatic URL decoding?
What is the recommended approach for handling URLs with encoded forward slashes in APIM?

Ranashekar Guda 2,820 Reputation points Microsoft External Staff Moderator

2025-06-04T23:20:24.9466667+00:00

Hello @Rishav Arora,
Thank you for reaching out. You're encountering an issue in Azure API Management (APIM) where encoded forward slashes (%2F) in the URL path are being automatically decoded to /, which causes routing problems and incorrect path resolution on the backend. This behavior is expected in APIM, as it automatically decodes URL-encoded characters in the path segment according to standard HTTP processing rules. There is no built-in configuration setting in APIM to preserve %2F in path parameters.

While APIM does not offer a direct policy to prevent this decoding, you can apply the url-decode policy with the ignoreError="true" attribute. This doesn’t stop the decoding of %2F, but it can help suppress errors when decoding fails or isn’t needed, allowing you to handle such scenarios more flexibly. That said, the recommended and more reliable approach is to avoid using slashes in path parameters altogether.

Instead, you can pass such values as query parameters or replace slashes with safe placeholder characters (like _slash_) and decode them on the backend. You may also consider using the rewrite-uri policy if you want to transform the incoming path into a format your backend can interpret correctly.

To troubleshoot and validate, we recommend checking the current policies in your APIM instance, enabling tracing to inspect how the URL is being handled, and testing with different formats (query params or encoded placeholders). Once a workaround is in place, confirm that your backend receives the intended value without decoding issues.
Ranashekar Guda 2,820 Reputation points Microsoft External Staff Moderator

2025-06-05T18:59:14.33+00:00

Hello @Rishav Arora,
Just checking in to see if above information was helpful. If you have any further updates on this issue, please feel free to post back.
Rishav Arora 20 Reputation points

2025-06-06T06:54:59.35+00:00

Hello @Ranashekar Guda ,

Thank you for your detailed response and the follow-up. I apologize for the delayed response on my end.

I greatly appreciate the comprehensive information you provided regarding the URL decoding behavior in Azure API Management. Your explanation clarifies why we're experiencing this issue with encoded forward slashes (%2F) being automatically decoded.

Following your recommendations, we have tested several approaches including the rewrite-uri policy and the url-decode policy with ignoreError="true". Unfortunately, these solutions did not resolve our specific use case, as the %2F characters are still being decoded before our policies can intercept them.

Currently, it is not feasible for us to modify our API design to avoid sending %2F in path parameters or to switch to query parameters, as this would require significant changes across multiple client applications and would impact our existing API contracts.

As an alternative approach, we are implementing a solution where we convert the affected string values to Base64 URL encoding on the client side and then decode them back to their original format in our backend services. We are currently testing this implementation to ensure it works reliably across all our scenarios.

Would you have any comments or recommendations regarding this Base64 URL encoding approach? Are there any potential limitations or considerations we should be aware of when implementing this workaround in the Azure API Management context?

Thank you again for your assistance and guidance on this matter.
Ranashekar Guda 2,820 Reputation points Microsoft External Staff Moderator

2025-06-10T18:14:03.89+00:00

Hello @Rishav Arora,
Following up to see if the below answer was helpful. If this answers your query, do click Accept Answer and Yes for was this answer helpful. And, if you have any further query do let us know.

Accepted answer

1 additional answer

Your answer

Ranashekar Guda 2,820 Reputation points Microsoft External Staff Moderator

2025-06-04T23:20:24.9466667+00:00

Hello @Rishav Arora,
Thank you for reaching out. You're encountering an issue in Azure API Management (APIM) where encoded forward slashes (%2F) in the URL path are being automatically decoded to /, which causes routing problems and incorrect path resolution on the backend. This behavior is expected in APIM, as it automatically decodes URL-encoded characters in the path segment according to standard HTTP processing rules. There is no built-in configuration setting in APIM to preserve %2F in path parameters.

While APIM does not offer a direct policy to prevent this decoding, you can apply the url-decode policy with the ignoreError="true" attribute. This doesn’t stop the decoding of %2F, but it can help suppress errors when decoding fails or isn’t needed, allowing you to handle such scenarios more flexibly. That said, the recommended and more reliable approach is to avoid using slashes in path parameters altogether.

Instead, you can pass such values as query parameters or replace slashes with safe placeholder characters (like _slash_) and decode them on the backend. You may also consider using the rewrite-uri policy if you want to transform the incoming path into a format your backend can interpret correctly.

To troubleshoot and validate, we recommend checking the current policies in your APIM instance, enabling tracing to inspect how the URL is being handled, and testing with different formats (query params or encoded placeholders). Once a workaround is in place, confirm that your backend receives the intended value without decoding issues.
Ranashekar Guda 2,820 Reputation points Microsoft External Staff Moderator

2025-06-05T18:59:14.33+00:00

Hello @Rishav Arora,
Just checking in to see if above information was helpful. If you have any further updates on this issue, please feel free to post back.
Rishav Arora 20 Reputation points

2025-06-06T06:54:59.35+00:00

Hello @Ranashekar Guda ,

Thank you for your detailed response and the follow-up. I apologize for the delayed response on my end.

I greatly appreciate the comprehensive information you provided regarding the URL decoding behavior in Azure API Management. Your explanation clarifies why we're experiencing this issue with encoded forward slashes (%2F) being automatically decoded.

Following your recommendations, we have tested several approaches including the rewrite-uri policy and the url-decode policy with ignoreError="true". Unfortunately, these solutions did not resolve our specific use case, as the %2F characters are still being decoded before our policies can intercept them.

Currently, it is not feasible for us to modify our API design to avoid sending %2F in path parameters or to switch to query parameters, as this would require significant changes across multiple client applications and would impact our existing API contracts.

As an alternative approach, we are implementing a solution where we convert the affected string values to Base64 URL encoding on the client side and then decode them back to their original format in our backend services. We are currently testing this implementation to ensure it works reliably across all our scenarios.

Would you have any comments or recommendations regarding this Base64 URL encoding approach? Are there any potential limitations or considerations we should be aware of when implementing this workaround in the Azure API Management context?

Thank you again for your assistance and guidance on this matter.
Ranashekar Guda 2,820 Reputation points Microsoft External Staff Moderator

2025-06-10T18:14:03.89+00:00

Hello @Rishav Arora,
Following up to see if the below answer was helpful. If this answers your query, do click Accept Answer and Yes for was this answer helpful. And, if you have any further query do let us know.

Answer 1

Hello @Rishav Arora,
Thank you for the update, and we appreciate the steps you've taken to address the issue. Using Base64 URL-safe encoding on the client side and decoding it on the backend is a practical and commonly used workaround when dealing with reserved characters like forward slashes in API paths. Since Azure API Management automatically decodes characters like %2F in the URL path, and this behavior can't be changed through policies, your approach helps avoid these issues without requiring changes to your existing API structure or client applications.Base64 URL encoding is safe for use in URLs because it avoids characters that can interfere with path parsing. It also ensures that the original value, including slashes, is preserved accurately. Just keep in mind that it will increase the length of the URL slightly, and the backend must correctly decode the values and handle any errors or invalid inputs gracefully. Also, make sure all your client applications use the same encoding format to avoid inconsistencies.

Rishav Arora 20 Reputation points

2025-06-13T09:01:50.5533333+00:00

Thank you @Ranashekar Guda , for validating our Base64 URL encoding approach!

We appreciate the implementation considerations you've highlighted - we'll ensure robust error handling in our backend and maintain consistent encoding across all client applications.

Thanks for the comprehensive guidance throughout this discussion!

Answer 2

Maxiem Wagenaar 0

@Rishav Arora Have you tried using %252F instead of %2F? That was a simple solution that worked for us.

Rishav Arora 20 Reputation points

2025-06-13T08:58:19.8566667+00:00

Thanks for the suggestion, @Maxiem Wagenaar , We haven't tried the %252F approach, and you're right that it should work since APIM would decode %25 to % leaving %2F intact.

However, we're sticking with base64 URL encoding for our use case. We have multiple special characters in our path params that get decoded by APIM, and we'd prefer to avoid the additional string manipulation and re-encoding overhead in our backend. Base64 URL encoding gives us a cleaner solution that handles all our encoded characters consistently.

Appreciate the input though - this could definitely help others facing similar issues!

Share via

URL Encoding Issue in Azure API Management - Encoded Forward Slash (%2F) Getting Decoded Automatically

1 additional answer

Your answer