Amazon API Gateway
Developer Guide

Use API Keys in API Gateway without Usage Plans Enabled


Since the API Gateway usage plans feature was launched on August 11, 2016, usage plans will be enabled for you in a region where you start using API Gateway the first time. In this case, you must use a usage plan to associate an API key with an API stage, skip any further discussions of this topic, and follow the instructions in Use API Gateway Usage Plans.

If you created an API Gateway API before then and have not enabled usage plans in the region since then, you can follow the instructions given in this section to associate an API key with an API stage to identify API callers, to restrict API access to those users with matching API keys, and to curtail abusive uses with different API keys.

To use an API key without enabling usage plans, you need to perform the following tasks:

  • Create an API key.

  • Enabled it on specific API methods.

  • Deploy the API to a stage.

  • Associate the key with the API stage.

  • Distribute the key to your customers and ask them to supply it in calls to the enabled API methods.

API keys are not meant as a security mechanism for controlling access to an API. To enable secure access control, use IAM permissions, custom authorizers or a Amazon Cognito User Pool.


  1. You must not have API Gateway usage plans enabled.

  2. You must have an API available in API Gateway. Follow the instructions in Creating an API.

  3. You must have deployed the API in API Gateway at least once. Follow the instructions in Deploying an API.

Use an API Key when Usage Plans Are Not Enabled


The following instructions apply only if usage plans are not enabled for your account in the chosen region. To associate an API key with an API stage in a usage plan, follow the instructions in Use API Gateway Usage Plans.

To use the API Gateway console to enable an API key without usage plans, follow these instructions:

  1. Sign in to the API Gateway console at

  2. Enable API key on an method:

    1. Choose a method under a resource of your choosing.

    2. Choose the Method Request box

    3. If API Key Required is set to false, choose the pencil icon next to it. Choose true from the drop-down list and then choose the check-mark icon to save the setting.

    Note that the steps above configure the API Gateway to enforce using API key on the method. Otherwise, the API key created following the instructions below will not be used for any of such calls.

  3. Deploy or redeploy the API for the requirement to take effect.

  4. Create an API key:

    1. In the API Gateway main navigation pane, choose API Keys.

    2. Choose Create API Key from the Actions drop-down menu.

    3. For Name, type a name for the API key entry.

    4. Choose either the Auto Generate option for API Gateway to generate the key or the Custom option for you specify the key value manually. A key value is an alphanumeric string of a size between 30 and 128 characters long.

    5. Optionally, type a description for the API key in the Description text box.

    6. Choose Save. Make a note of the key displayed in API key. Callers of the enabled method must specify the key value in the x-api-key header.

    7. Choose Show next to API key to view the newly created API key. Your customers must provide this key as the x-api-key header value when they call this method.

      The generated API key is enabled by default, allowing the API caller to access the API, provided that the supplied API key matches the one configured. To prevent the apps with the specified API key from accessing the API, choose Edit, deselect the Enabled option, and then choose Save.

  5. Associate an API key with an API stage

    1. Under API Stage Association, choose the name of the API from the Select API drop-down list.

    2. Choose the name of a stage of the chosen API from the Select stage drop-down list.

    3. Choose Add to save the setting.


    The console UI elements shown above are not available if usage plans have been enabled for your account and region.

  6. Distribute the API key to your customers and ask them to add the key as the x-api-key header to call the key-required method. For example, if the API key of hzYAVO9Sg98nsNh81M84O2kyXVy6K1xwHD8 is required on the GET / method in the test stage of an API (yd4f8dz2vf), the caller must submit the following request to invoke the method.

    GET /test HTTP/1.1 Host: Content-Type: application/json x-api-key: hzYAVO9Sg98nsNh81M84O2kyXVy6K1xwHD8