How to require an API key in AWS API Gateway

I am working on the back end API that is going to be consumed by a mobile app. The backend logic is going to change over the next few iterations, but I expect the API to be stable. I wanted to deploy the API so that the mobile developer could start consuming it, but I wanted to restrict who could call my functions. An API key seemed like the easiest way to go.

The first time I do something, I like to use the AWS console. If this is something I end up doing regularly I will set it up in Terraform.

Actually securing API Gateway with an API key took a few steps, and I couldn't find all of them in the same place. This isn't an exhaustive discussion, just the steps I took to secure my API. The application I am building is a tic-tac-toe game that initially will have 2 functions, one for creating a new game and the other for making a move in the game.

1. Create REST API The first decision I had to make was whether to go with an HTTP API or a REST API. My tic-tac-toe game doesn't really seem to fit the REST model, but my Google searches lead me to believe that HTTP API did not support API keys, so I went with REST.

2. Create Resource and methods I decided to go with a single resource called game. I added a POST method to call the new game function and PUT method for the make-move function.

3. Require API Keys For the methods you set up, click on the Method Request. The settings of the Method Request allow you to specify API Key Required, which you will set to true.

4. Deploy the API From the resources section of your API, choose Deploy API. You can choose an existing stage if you have one set up, or you can create a new stage.

5. Create API Key In the lefthand menu choose API keys and then in the Actions dropdown choose Create API Key. Enter a name for your key, and either select Auto-Generate a key, or select Custom and enter a key, then click save. After you have saved the key, you will be able to see the value at any time from the API gateway console by selecting the key, then clicking on Show.

6. Create a Usage Plan Your API key has to be attached to a usage plan, and the usage plan is associated with an API and a Stage. From the lefthand menu, choose Usage Plans. Click Create to make a new usage plan. Give your plan a name, and choose whether you want to enable throttling.

7. Associate Stage with Usage Plan Your usage plan has to be applied to an API within a stage. On the Usage Plans screen, press Add API Stage. Choose the API and the stage you deployed it to in step 4.

8. Associate API Key with API Key In the Usage Plan, choose the API Keys tab and Add API Key to Usage Plan. Choose the key you crated in Step 5.

9. Set the API Key Source Settings appears twice in the left hand menu, you want the first instance, which applies just to your API, not the one at the bottom which applies to your whole account. From the settings page, set the API Key Source to HEADER.

10. Test your API You are now ready to call your API from curl or Postman. You can find the base URL of your API on the Stages screen. You can see the API key you created from the API Keys menu. You need to specify the header x-api-key and the value for that header will be the API key that you created.

If you fail to supply the header, or have an incorrect key, you should receive a 403 - Forbidden. With the header set correctly you should receive your function's normal response.