Debug Authenticated Routes

Debug Authenticated Routes

Purpose

Systematically diagnose and fix failures on protected API routes, especially:

• 401 Unauthorized
• 403 Forbidden
• 404 Not Found that only occurs under auth

When to use

Use this skill when:

• A protected endpoint returns 401 even after login
• A protected endpoint returns 403 unexpectedly (permission mismatch)
• A route returns 404 despite being implemented (registration/prefix/method mismatch)
• Cookie/session or bearer token auth behaves inconsistently
• An auth middleware change caused broad regressions

Inputs

Provide (or collect) the following:

• Endpoint: method + path
• A failing request example (sanitized):
  • headers (redact secrets)
  • cookie names (redact values)
  • body/query/params
• Observed response:
  • status code
  • response body (sanitized)
• Expected behavior:
  • required user role/permission
  • expected status code and response shape
• Environment context:
  • local vs staging vs production
  • reverse proxy / gateway presence (if any)

Outputs

• Root-cause diagnosis (which layer is failing and why)
• Minimal fix proposal (code/config changes)
• Verification evidence (how to confirm the fix)
• Optional: regression-prevention recommendation (test/monitoring)

Steps

1) Capture a reproducible failing case (evidence-first)

• Use the request capture template to record a sanitized request + response.
• Ensure the request is reproducible (curl/Postman/test invocation).

2) Confirm the auth context is actually attached

• Cookie auth: cookie name present, expected scope/flags for the environment.
• Bearer auth: Authorization header present, correctly formatted, token not expired.

3) Classify by status code and trace the request path

• 401: authentication not established or not recognized.
• 403: authentication established, authorization denies.
• 404: routing/registration/prefix/method mismatch or route shadowing.
• 5xx: unhandled exception or downstream dependency failure.

Trace the request through these layers:

1. Request parsing (body, content-type)
2. Authentication middleware
3. Authorization middleware (roles/permissions)
4. Validation middleware (if any)
5. Route matching (method + path + prefix)
6. Controller and service execution

4) Identify the smallest change that fixes the root cause

Common root-cause categories:

• Cookie/session transport issues (flags, proxy behavior)
• Bearer token validation issues (expiry, issuer/audience, signing keys)
• Permission checks (role/claims mismatch, wrong tenant/org id)
• Route registration issues (prefix, method, import/registration order)

5) Approval checkpoint (required for auth/policy changes)

Before applying any change that impacts authentication/authorization behavior:

• Summarize the root cause in 1–3 bullets.
• Propose the minimal fix.
• List expected side effects / risks.
• Obtain explicit approval.

6) Apply the minimal fix

• Prefer fixing root causes (wiring, order, prefix, permission rule) over bypasses.
• Avoid weakening production controls.

7) Verify with evidence

• Re-run the original failing request using the same auth context.
• Run at least one negative test:
  • invalid/missing auth → expect 401
  • insufficient permission → expect 403
• If the route writes data: verify expected side effects (created/updated records, downstream triggers).
• Capture sanitized logs/metrics that confirm expected status codes.

Verification

• A sanitized, reproducible failing request is captured (command + response)
• Root cause is identified (which layer fails and why)
• Fix resolves the original failure
• Re-running the request returns expected status and response shape
• Negative tests behave correctly (401 for missing auth, 403 for insufficient permission)
• Side effects verified for write endpoints (if applicable)
• No secrets/tokens were recorded in outputs

Boundaries

• MUST NOT paste real tokens, session cookies, API keys, or credentials into artifacts
• MUST NOT weaken production auth/permission checks to “make the request work”
• MUST gate auth/permission policy changes behind explicit approval
• SHOULD add a regression test when the issue was systemic (middleware order, shared auth logic)
• SHOULD NOT assume cookie/token is attached without confirming

Included assets

• Templates:
  • ./templates/request-capture.md: sanitize and capture a failing request/response
  • ./templates/debugging-checklist.md: step-by-step diagnostic checklist with approval gate
• Examples: ./examples/ includes typical 401/403/404 triage notes.