AWS企業帳號代開 AWS API Gateway 自訂域名（Custom Domain）報 403 Missing Authentication Token

先搞懂：403 Missing Authentication Token 不一定是「沒帶 Token」

很多人第一次看到 AWS API Gateway 回傳 403 Missing Authentication Token，直覺都會以為是授權失敗、JWT 過期，或是 API Key 沒帶對。但在 API Gateway 的世界裡，這個訊息經常不是字面意思。它更常代表一件事：請求沒有命中任何可用的路由、資源或方法。

當你直接用 API Gateway 的原始 Invoke URL 測試通常正常，可是一換成自訂域名（Custom Domain）就開始報 403，問題多半不在後端程式，而在入口層。常見的根源包括：Base Path Mapping 設錯、Stage 對不上、URL 路徑少了一段、HTTP API 與 REST API 的路由規則不同，或者 DNS 指到錯誤的 API Gateway 端點。

換句話說，這類 403 的排查邏輯，不是先看權限，而是先看「請求有沒有走到正確的 API、正確的 stage、正確的 resource path」。只要入口錯了一點點，API Gateway 就會直接回你這個讓人困惑的錯誤。

一、最常見的原因：Base Path Mapping 沒對上

自訂域名最常出問題的地方，就是 Base Path Mapping。它負責把某個網域底下的路徑，對應到特定的 API 與 Stage。若這裡設定錯誤，API Gateway 收到請求後找不到對應資源，就可能回傳 403 Missing Authentication Token。

例如你在自訂域名底下設定：

api.example.com /v1 → 對應到 api-id 的 prod stage

那麼真正可用的請求可能是：

https://api.example.com/v1/users

如果你少了 /v1，直接打成：

https://api.example.com/users

API Gateway 就未必知道要把這個請求導到哪裡，於是報錯。這種情況在切換團隊、重構 API 路徑、或把不同版本 API 放在同一個自訂域名下時特別常見。

檢查重點

請確認以下幾件事：

• 自訂域名是否已正確綁定到 API Gateway。
• Base Path 是否真的和你請求的路徑一致。
• 對應的 Stage 是否存在，而且有部署成功。
• 同一個自訂域名下，是否有多個 Base Path 發生衝突。

如果你是 REST API，Base Path Mapping 尤其重要；如果你是 HTTP API，則更要注意路由與 $default route 的配置方式，因為兩者思路不太一樣。

二、Stage 或部署版本不一致，請求就會失蹤

API Gateway 很多問題不是「程式寫錯」，而是「改了設定卻沒部署」。特別是 REST API，只要你修改了 resource、method、integration 或 authorizer，卻沒有重新部署到對應的 Stage，外部請求看到的還是舊版本。

這在自訂域名場景下更容易被放大。因為你平常可能會用 Invoke URL 測試某個 stage，一切都正常；但自訂域名映射到的是另一個 stage，或者映射的 stage 根本沒部署最新路由，最後結果就是 403。

常見例子：

• 你在 dev stage 測試正常，但自訂域名指向的是 prod stage。
• 你新增了 POST /orders，但只部署了部分資源。
• 你改了 Lambda integration，卻忘了重新 deploy。

這類情況最麻煩的地方在於，前端看起來只是「同一個網址突然不能用了」，但其實底層已經換了版本。排查時先看 API Gateway 控制台中的 Deployments 和 Stage 設定，往往比盯著後端 log 更有效率。

三、路徑拼接錯誤：少一層、多一層，都會報 403

自訂域名下的 URL 最容易出錯的，就是路徑拼接。很多團隊會把 API base path、版本號、resource path 混在一起，最後自己也分不清到底哪一段由誰負責。

假設設定如下：

Custom Domain: api.example.com
Base Path Mapping: /service → prod stage
Resource Path: /v1/users

那最終路徑就應該是：

https://api.example.com/service/v1/users

如果你誤以為 /service 已經包含在 API resource path 裡，改成：

https://api.example.com/v1/users

請求就會失敗。反過來，如果你在應用程式裡又額外拼了一次 /service，變成：

https://api.example.com/service/service/v1/users

一樣找不到對應資源。

這種問題在 Postman、前端環境變數、反向代理、Serverless Framework、Terraform、CDK 等多個層級同時配置時最常見。很多人以為自己只是「改了 domain」，其實已經無意間改了 URL 結構。

實務上最該先檢查的三個點

第一，請先確認自訂域名底下到底有沒有 Base Path。第二，確認 API 定義中的 resource path 是否包含版本號。第三，確認請求端是否又額外加了前綴。只要三者有一個重疊或遺漏，就很容易中招。

四、REST API 與 HTTP API 的設定邏輯不同

AWS企業帳號代開 AWS 這兩種 API 類型長得很像，但背後的規則差很多。很多人在切換方案時，會把 REST API 的思維直接套到 HTTP API，然後被 403 狠狠提醒一次。

REST API 比較依賴 resource、method、stage、base path mapping；HTTP API 則更偏向 route、integration、$default route、API mapping。若你以為只要把自訂域名綁上去就能通，實際上 route 沒設好，請求還是會被拒絕。

尤其是 HTTP API 的 $default route，如果你的請求沒有命中任何明確路由，卻又沒有配置預設路由，API Gateway 也可能直接回 403。這時候錯誤訊息看起來像認證失敗，實際上只是找不到路由。

因此，遇到自訂域名 403 時，先搞清楚你用的是哪一種 API，再對照它的配置邏輯，不要混用文件概念。這一步經常能少掉一半的排查時間。

五、授權設定也可能是真的問題，但通常不是第一嫌疑

雖然 Missing Authentication Token 多半不是單純的認證問題，但授權設定仍然值得檢查。尤其當你的 API 有以下幾種保護方式時，問題可能藏在這裡：

• IAM Authorization
• Cognito User Pool Authorizer
• AWS企業帳號代開 Lambda Authorizer
• API Key 與 Usage Plan

不過要注意，真正的授權失敗和路由找不到，錯誤表現不一定一致。有時你會看到 401，有時是 403，有時卻仍然是 Missing Authentication Token。這也是為什麼不能只靠錯誤字面判斷，而要回到請求入口逐層確認。

如果你的 API 有 authorizer，請檢查：

• 請求是否帶了正確的 Authorization header。
• Header 名稱是否被代理層改寫。
• API Key 是否在要求的 method 上正確啟用。
• Resource policy 是否限制了特定來源 IP、VPC Endpoint 或帳號。

AWS企業帳號代開 當你使用自訂域名後，還要注意前面是否有 CloudFront、ALB、反向代理或 WAF。這些中間層有時會改掉 Host、Path 或 Header，導致 API Gateway 收到的請求跟你想像的不一樣。

六、DNS、憑證與端點類型也不能忽略

自訂域名不是只有綁定那麼簡單，背後還涉及 DNS 與憑證。若你使用的是 Regional custom domain 或 Edge-optimized custom domain，配置方式不同，對應的 ACM 憑證區域也不同。雖然這些設定錯誤時未必直接表現為 403，但在實務上常常會一起出現，讓人誤判方向。

例如：

• DNS 已經指向 CloudFront，但自訂域名仍對應到舊的 API Gateway 配置。
• ACM 憑證放在錯誤區域，導致網域行為異常。
• 同一個域名在不同環境切換時，Alias 記錄沒更新。

如果你最近剛做過遷移，像是從 REST API 改成 HTTP API，或從 edge-optimized 改成 regional，請務必確認整條鏈都已經更新。很多「看起來像 API 問題」的錯誤，其實是 DNS 還沒完全切過去。

七、最有效的排查順序

遇到 AWS API Gateway 自訂域名報 403 Missing Authentication Token，最好的方式不是亂試，而是按順序縮小範圍。下面這個順序，通常最省時間：

1. 先用 API Gateway 原始 Invoke URL 測試，確認 API 本體是否正常。
2. AWS企業帳號代開 確認自訂域名已正確綁定到對應 API 與 Stage。
3. 檢查 Base Path Mapping 或 API Mapping 是否正確。
4. 確認請求路徑是否少了前綴、多了前綴，或大小寫不一致。
5. 確認 REST API 是否已重新部署，HTTP API 是否已更新 route。
6. 再檢查 authorizer、API Key、resource policy、WAF 等權限層。
7. 最後才看 DNS、憑證與中間代理層。

這個順序的核心邏輯很簡單：先查「路由有沒有對」，再查「授權有沒有對」，最後才查「外部網路層有沒有對」。因為大多數 Missing Authentication Token 的本質，都是請求沒走到你以為的那條路。

八、幾個最容易忽略的小細節

除了大方向之外，還有一些細節也很容易讓人卡住：

• URL 末尾多一個或少一個斜線，有時會影響路由命中。
• Path parameter 沒填值，例如 /users/{id} 實際卻打成 /users/。
• 大小寫不一致，尤其當前端與後端對 resource path 的命名規則不同時。
• 使用瀏覽器直接訪問時，OPTIONS 預檢請求未配置好，導致看起來像主請求失敗。
• AWS企業帳號代開 多環境共用一個自訂域名，但 Base Path Mapping 已被其他環境覆蓋。

這些問題看起來很小，但在 AWS 服務鏈條裡，任何一個小錯誤都可能讓你最後只看到同一個 403。真正麻煩的不是錯誤本身，而是它把原因包得很像。

結語：把 403 當成「路由失配」來看，通常更接近真相

AWS API Gateway 自訂域名報 403 Missing Authentication Token，最怕的就是把它當成單純的認證問題。實際上，這個錯誤常常是在提醒你：請求路徑、Base Path、Stage、Route、部署版本，至少有一個環節沒有對上。

如果你只記一個原則，那就是：先確認請求是否真的命中了正確的 API 入口。只要入口對了，後面的認證、授權、整合才有討論空間；如果入口不對，再多查 JWT、IAM 或 Lambda Authorizer 都是在繞路。

下次再看到這個錯誤時，不妨先回到最基本的地方：自訂域名指到哪個 API？Base Path 是什麼？Stage 有沒有部署？路徑是不是拼錯？通常把這幾個問題釐清，答案就已經浮出來了。