Choose an API key source in API Gateway

When you associate a usage plan with an API and enable API keys on API methods, every incoming request to the API must contain an API key. API Gateway reads the key and compares it against the keys in the usage plan. If there is a match, API Gateway throttles the requests based on the plan's request limit and quota. Otherwise, it throws an InvalidKeyParameter exception. As a result, the caller receives a 403 Forbidden response.

Your API Gateway API can receive API keys from one of two sources:

HEADER

You distribute API keys to your customers and require them to pass the API key as the X-API-Key header of each incoming request.

AUTHORIZER

You have a Lambda authorizer return the API key as part of the authorization response. For more information on the authorization response, see Output from an API Gateway Lambda authorizer.

Note

For best practices to consider, see Best practices for API keys and usage plans.

To choose an API key source for an API by using the API Gateway console

1. Sign in to the API Gateway console.

2. Choose an existing API or create a new one.

3. In the main navigation pane, choose API settings.

4. In the API details section, choose Edit.

5. Under API key source, select Header or Authorizer from the dropdown list.

6. Choose Save changes.

To choose an API key source for an API by using the AWS CLI, call the update-rest-api command as follows:

aws apigateway update-rest-api --rest-api-id 1234123412 --patch-operations op=replace,path=/apiKeySource,value=AUTHORIZER

To have the client submit an API key, set the value to HEADER in the preceding CLI command.

To choose an API key source for an API by using the API Gateway REST API, call restapi:update as follows:

PATCH /restapis/fugvjdxtri/ HTTP/1.1
Content-Type: application/json
Host: apigateway.us-east-1.amazonaws.com
X-Amz-Date: 20160603T205348Z
Authorization: AWS4-HMAC-SHA256 Credential={access_key_ID}/20160603/us-east-1/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature={sig4_hash}

{
  "patchOperations" : [
    {
        "op" : "replace",
        "path" : "/apiKeySource",
        "value" : "HEADER"
    }
  ]
}

To have an authorizer return an API key, set the value to AUTHORIZER in the previous patchOperations input.

Depending on the API key source type you choose, use one of the following procedures to use header-sourced API keys or authorizer-returned API keys in method invocation:

To use header-sourced API keys:

1. Create an API with desired API methods, and then deploy the API to a stage.

2. Create a new usage plan or choose an existing one. Add the deployed API stage to the usage plan. Attach an API key to the usage plan or choose an existing API key in the plan. Note the chosen API key value.

3. Set up API methods to require an API key.

4. Redeploy the API to the same stage. If you deploy the API to a new stage, make sure to update the usage plan to attach the new API stage.

The client can now call the API methods while supplying the x-api-key header with the chosen API key as the header value.

To use authorizer-sourced API keys:

1. Create an API with desired API methods, and then deploy the API to a stage.

2. Create a new usage plan or choose an existing one. Add the deployed API stage to the usage plan. Attach an API key to the usage plan or choose an existing API key in the plan. Note the chosen API key value.

3. Create a token-based Lambda authorizer. Include, usageIdentifierKey:{api-key} as a root-level property of the authorization response. For instructions on creating a token-based authorizer, see Example TOKEN authorizer Lambda function.

4. Set up API methods to require an API key and enable the Lambda authorizer on the methods as well.

5. Redeploy the API to the same stage. If you deploy the API to a new stage, make sure to update the usage plan to attach the new API stage.

The client can now call the API key-required methods without explicitly supplying any API key. The authorizer-returned API key is used automatically.