Handling API Gateway's "Missing Authentication Token" Error (404) Correctly

If you've ever worked with AWS API Gateway, you might have encountered the dreaded "Missing Authentication Token" message.
This typically happens when a user tries to access an endpoint without a valid authentication token. However, what confuses many of us is that this error can also appear even when the correct token is provided but the requested resource or path does not exist.

In this blog post, I'll explain why this happens and how you can modify the response to make it more user-friendly by returning a custom 404 error instead of the default 404 "Missing Authentication Token". While there are other potential causes for this error, we were have confirmed that the token was sent correctly and wanted to focus on improving the response message for missing resources.

Why Does "Missing Authentication Token" Appear Even with a Token?

AWS API Gateway throws the "Missing Authentication Token" error when:

• The request is sent to an incorrect or non-existent resource path.

• The method (GET, POST, etc.) does not exist for the requested resource.

• The API Gateway has authentication enabled but the request does not meet the authentication criteria

By default, when a user accesses a non-existent path, API Gateway responds with a 404 "Missing Authentication Token" error instead of a more intuitive 404 "Not Found". This can mislead users into thinking it's an authentication issue when in reality, they are hitting an invalid path, as it was in my case.

How to Change the "Missing Authentication Token" Response

You can customize this response in API Gateway Gateway Responses by following these steps:

• Open your API Gateway in the AWS Console.

• Navigate to Gateway Responses.

• Find and select "Missing Authentication Token".

• Change the status code to 404 if it was not already set.

• In the Response Template modify the Template Body to return a more meaningful message, such as:
  

{
  "error": "Not Found",
  "message": "Wrong or non-existent path entered."
}

Keep the Content type as application/json.

The example is shown in the image below.

Now, lets test it with Postman!

I have refined the message a bit :)

Automating the Change Using a YAML Template

If you want to apply this change programmatically, you can use a CloudFormation or OpenAPI definition file. Below is an example test.yml file you can use to modify the Missing Authentication Token response:

openapi: "3.0.1"
info:
  title: "Test API"
  version: "1.0"
paths: {}
x-amazon-apigateway-gateway-responses:
  MISSING_AUTHENTICATION_TOKEN:
    statusCode: 404
    responseTemplates:
      application/json: |
        {
          "error": "Not Found",
          "message": "Wrong or non-existent path entered."
        }

Steps to Deploy the Template

• Import the test.yml file inside the API Gateway console.

• Deploy the API.

• If testing manually, set the method implementation to Mock and then deploy.

If you're using a CloudFormation template.yml, you can apply a similar approach by modifying the GatewayResponse resource for MISSING_AUTHENTICATION_TOKEN.

Changing the Missing Authentication Token message to return a custom 404 error instead of default one makes debugging easier for developers and improves the API's usability.

Have you encountered this issue before? Let me know how you handled it in the comments!

Comments

[Airat Yusuff]

Thanks for sharing! I ran into this issue yesterday and wrote about it in my documentation post.
I had also thought it was a misleading error response because I had to figure out it gets returned when accessing paths undefined within the gateway.
I’ll try this out with Terraform and configure for a better response too.