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

[Irash-Perera]

Addressed Issue: #4949

The tutorial at en/docs/api-gateway/policies/passing-a-custom-authorization-token-to-the-backend.md
instructed users to create an API using the following hosted sample backend as the endpoint:

http://wso2cloud-custom-auth-header-sample-1-0-0.wso2apps.com/custom-auth-header/validate-header

This endpoint is no longer available, so the tutorial could not be completed as written. This PR replaces the dead hosted endpoint with instructions for running the equivalent sample backend locally.

Changes

1. New step: start the sample backend server locally

A new Step 2 guides the user to run the sample validation backend from the WSO2 API Manager Samples repository (custom-auth-token-backend directory):

git clone https://github.com/wso2/samples-apim
cd samples-apim/custom-auth-token-backend
python3 server.py

PR for the sample backend in the samples-apim repository: Add sample backend server for validating custom authorization tokens #165

The server listens on http://localhost:8080, accepts any path and method, and authorizes a request only when the Authorization header is exactly Bearer 1234 - the same contract the old hosted backend implemented. It also echoes back the headers it received and logs every request to the terminal, so users can verify exactly what
the gateway forwarded to the backend.

2. Updated API endpoint

The endpoint in the API creation table now points to the local server:

http://localhost:8080/custom-auth-header/validate-header

3. Step numbering and cross-reference fixes

The step list previously had broken numbering (…5, 6, then 5, 6, 7, 24). Steps now run sequentially from 1 to 11, and in-text references ("the token that you got in step 8", "the policy that you just created by following Step 4") were updated to match.

[coderabbitai]

📝 Walkthrough

Summary

• Updated the custom authorization token tutorial to use a locally run sample backend.
• Added backend setup instructions and documented the expected local endpoint.
• Revised API, policy, deployment, token, and invocation steps for a sequential 1–11 flow.
• Clarified request headers, expected responses, and backend verification details.

Walkthrough

The tutorial now uses a locally running sample backend that expects Authorization: Bearer 1234. It updates API setup and endpoint instructions, revises policy attachment and deployment steps, and adds guidance for obtaining an application token and invoking the API. The verification section explains that the backend receives the value from the Custom header as Authorization and that the Custom header is removed.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the fix, but it does not follow the required template and misses most mandated sections.	Rewrite the PR description using the repository template and add the missing sections such as Purpose, Goals, Approach, Release note, Documentation, and Test environment.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: replacing the broken backend endpoint in the tutorial.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with 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.

Inline comments:
In
`@en/docs/api-gateway/policies/passing-a-custom-authorization-token-to-the-backend.md`:
- 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.
- Around line 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.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 533cb5c1-5ad7-4741-882d-085a52e453f4

📥 Commits

Reviewing files that changed from the base of the PR and between acd83ed and 04d0ef3.

⛔ Files ignored due to path filters (2)

• en/docs/assets/img/learn/api-gateway/message-mediation/custom-header-response.png is excluded by !**/*.png
• en/docs/assets/img/learn/custom-auth-backend-cli-output.png is excluded by !**/*.png

📒 Files selected for processing (1)

• en/docs/api-gateway/policies/passing-a-custom-authorization-token-to-the-backend.md

[coderabbitai]

📐 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

[coderabbitai]

📐 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.