How can I troubleshoot 403 "missing authentication token" errors when invoking API Gateway REST or HTTP APIs with a custom domain name?

Last updated: 2022-11-11

I followed the instructions to set up a custom domain name for my Amazon API Gateway REST or HTTP API. I am getting a 403 "Missing Authentication token" error when I invoke the API. How can I troubleshoot and resolve this error?

Short description

API Gateway APIs with custom domain names return the 403 "Missing Authentication token" error when invoking the API if the URL path is incorrect.

Note: Using the API Gateway API stage URL won't return the 403 "Missing Authentication token" error.

Resolution

Custom domain names configured for API Gateway APIs use API mappings to connect API stages to send traffic to APIs through the custom domain name. API mappings have an API, stage, custom domain name, and optionally a path to use for the mapping. For more information, see Working with API mappings.

In the following example, the custom domain "https://api.example.com" API mapping is configured as follows:

API Example Stage Path Default URL Custom Domain URL
abcd3456ef API 1 dev (none) https://abcd3456ef.execute-api.us-east-1.amazonaws.com/dev https://api.example.com
wxyz1234ab API 2 test orders https://wxyz1234ab.execute-api.us-east-1.amazonaws.com/test https://api.example.com/orders
mnop5678qr API 3 prod customers https://mnop5678qr.execute-api.us-east-1.amazonaws.com/prod https://api.example.com/customers

In this example configuration, a request made to API 1 using the URL https://abcd3456ef.execute-api.us-east-1.amazonaws.com/dev/resourceA routes traffic to "resourceA" successfully. This is because the request is made to the resource for the stage name "dev". However, the same request using the URL https://api.example.com/dev/resourceA returns a 403 "Missing Authentication token" error. This error occurs because the stage "dev" is mapped to the (none) path of the custom domain name. To route requests to "resourceA" using the custom domain name, make sure that the URL is https://api.example.com/resourceA.

Similarly, the custom domain name URL equivalent to https://wxyz1234ab.execute-api.us-east-1.amazonaws.com/test/resourceB is https://api.example.com/orders/resourceB. This is because the "test" stage of API 2 is mapped to the path "orders" in the custom domain API mapping.