Skip to content

Fix broken backend endpoint in "Passing a Custom Authorization Token to the Backend" tutorial #11585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Irash-Perera wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fix broken backend endpoint in "Passing a Custom Authorization Token to the Backend" tutorial #11585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 38 additions & 13 deletions ...ocs/api-gateway/policies/passing-a-custom-authorization-token-to-the-backend.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ different (or a custom generated) authorization token than the application gener
token exchange mechanism in mediation logic of the API. In this tutorial, we explain how to pass a custom authorization
token that is different to the authorization token generated for the application.

In this tutorial, you have a sample JAX-RS backend and it always expects 1234 as the authorization token. In your API
In this tutorial, you have a sample backend that always expects 1234 as the authorization token. In your API
request, you pass the token that is generated in the `Authorization` header, and 1234 in a `Custom` header.
The mediation extension you write extracts the value of the `Custom` header, and sets it as the `Authorization` header
before sending it to the backend.
Expand All @@ -26,16 +26,41 @@ Here's a summary:
</sequence>
```

2. Log in to the **API Publisher**, create a new REST API with the information given in the table below by following the instructions in [Create a REST API]({{base_path}}/api-design-manage/design/create-api/create-rest-api/create-a-rest-api/).
2. Start the sample backend server. Let's use the custom authorization token sample backend server as the backend for the API. It accepts any path and method, and authorizes a request only when the `Authorization` header is exactly `Bearer 1234`. On success it returns HTTP 200 with "Request Received."; otherwise HTTP 401.

1. Clone the [WSO2 API Manager Samples](https://github.com/wso2/samples-apim) repository.

```bash
git clone https://github.com/wso2/samples-apim
```

2. Navigate to the `custom-auth-token-backend` directory.

```bash
cd samples-apim/custom-auth-token-backend
```

3. Run the server.

```bash
python3 server.py
```

Once the above steps are done, the backend server will be running on `http://localhost:8080`.
[![CLI output]({{base_path}}/assets/img/learn/custom-auth-backend-cli-output.png){: style="width:65%"}]({{base_path}}/assets/img/learn/custom-auth-backend-cli-output.png)

Incoming requests and their headers are printed directly to the terminal, so you can verify what the gateway forwarded to the backend.

3. Log in to the **API Publisher**, create a new REST API with the information given in the table below by following the instructions in [Create a REST API]({{base_path}}/api-design-manage/design/create-api/create-rest-api/create-a-rest-api/).

| Field | Sample Value |
|---------------|----------------------|
| Name | TestCustomHeader |
| Context | /testcustomheader |
| Version | 1.0.0 |
| Endpoint | http://wso2cloud-custom-auth-header-sample-1-0-0.wso2apps.com/custom-auth-header/validate-header |
| Endpoint | http://localhost:8080/custom-auth-header/validate-header |

3. Navigate to the **API Configurations** --> **Policies** tab. Create a new policy with the information given in the table below by following the instructions in [Create a Policy]({{base_path}}/api-design-manage/design/api-policies/create-policy/).
4. Navigate to the **API Configurations** --> **Policies** tab. Create a new policy with the information given in the table below by following the instructions in [Create a Policy]({{base_path}}/api-design-manage/design/api-policies/create-policy/).

| Section | Field | Sample Value |
|---------------------------|-------------------|-----------------------|
Expand All @@ -47,24 +72,24 @@ Here's a summary:
| Gateway Specific Details | Policy File | `tokenExchange.j2` file you created |
| Policy Attributes | N/A | N/A |

4. Next, find the **Custom Authorization Token** policy that you just created by following Step 3, from the `Request` tab of the policy list. Drag and drop this policy to the desired API operation(s) by following the instructions in [Attach Policies]({{base_path}}/api-design-manage/design/api-policies/attach-policy/).
5. Next, find the **Custom Authorization Token** policy that you just created by following Step 4, from the `Request` tab of the policy list. Drag and drop this policy to the desired API operation(s) by following the instructions in [Attach Policies]({{base_path}}/api-design-manage/design/api-policies/attach-policy/).

[![Custom Authorization Token Policy]({{base_path}}/assets/img/design/api-policies/custom-authorization-token-policy.png)]({{base_path}}/assets/img/design/api-policies/custom-authorization-token-policy.png)

5. Finally, scroll down and click on the **Save** button in order to apply the attached policies to the API.
6. Finally, scroll down and click on the **Save** button in order to apply the attached policies to the API.

[![Disable Chunking]({{base_path}}/assets/img/design/api-policies/save-api-for-custom-authorization-token-policy.png)]({{base_path}}/assets/img/design/api-policies/save-api-for-custom-authorization-token-policy.png)

6. Make sure to navigate to the **Deployments** tab and click on **Deploy New Revision** button. Also, if the API is not in `PUBLISHED` state, navigate to the **Lifecycle** tab and publish your API.
7. Make sure to navigate to the **Deployments** tab and click on **Deploy New Revision** button. Also, if the API is not in `PUBLISHED` state, navigate to the **Lifecycle** tab and publish your API.

5. Go to the **Developer Portal**, subscribe and obtain a token to invoke the published API.
8. Go to the **Developer Portal**, subscribe and obtain a token to invoke the published API.

!!! tip
Follow the instructions in [here]({{base_path}}/api-developer-portal/manage-application/generate-keys/generate-api-keys/#generating-application-keys) to generate an application access token.

@coderabbitai coderabbitai Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use descriptive link text.

Replace [here] with text describing the destination, such as [Generate application keys], to improve accessibility and link discoverability.

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 88-88: Link text should be descriptive

(MD059, descriptive-link-text)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@en/docs/api-gateway/policies/passing-a-custom-authorization-token-to-the-backend.md`
at line 88, Replace the non-descriptive “[here]” link text in the application
access token instructions with descriptive text such as “Generate application
keys,” while preserving the existing destination URL.

Source: Linters/SAST tools


6. Install any REST client in your machine. We use [cURL](http://curl.haxx.se/download.html) here.
9. Install any REST client in your machine. We use [cURL](http://curl.haxx.se/download.html) here.

7. Go to the command line, and invoke the API using the following cURL command.
10. Go to the command line, and invoke the API using the following cURL command.
In this command, you pass the token that
the backend expects, i.e., 1234, in the **`Custom`** header with the authorization token that the system generates in
the **`Authorization`** header.
Expand All @@ -82,12 +107,12 @@ the **`Authorization`** header.
```

!!! info
- **<access token&gt;** is the token that you got in step 7.
- **<access token&gt;** is the token that you got in step 8.
- **<API URL&gt;** appears on the API's **Overview** page in the API Developer Portal. Copy the HTTP endpoint.
If you select the HTTPs endpoint, be sure to run the cURL command with the -k option.
Comment on lines +110 to 112

@coderabbitai coderabbitai Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use the standard HTTPS capitalization.

Change HTTPs to HTTPS for consistent user-facing terminology.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@en/docs/api-gateway/policies/passing-a-custom-authorization-token-to-the-backend.md`
around lines 110 - 112, Update the endpoint description near the API URL
instructions to use the standard “HTTPS” capitalization instead of “HTTPs,”
preserving the existing guidance and formatting.


24. Note the response that you get in the command line. According to the sample backend used in this tutorial,
you get the response as "Request Received."
11. Note the response that you get in the command line. According to the sample backend used in this tutorial,
you get the response as "Request Received.". You can also check the backend server's terminal to verify that the `Authorization` header received by the backend is `Bearer 1234` (swapped in from the `Custom` header) and that the `Custom` header has been removed.

[![]({{base_path}}/assets/img/learn/api-gateway/message-mediation/custom-header-response.png)]({{base_path}}/assets/img/learn/api-gateway/message-mediation/custom-header-response.png)

Expand Down
Binary file modified en/docs/assets/img/learn/api-gateway/message-mediation/custom-header-response.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added en/docs/assets/img/learn/custom-auth-backend-cli-output.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.