API keys and usage plans in AWS - Commands & Configuration

Introduction

API keys help control who can use your web services and how much they can use them. Usage plans set limits on how many requests each user can make to keep your service stable and fair.

When you want to limit how many times a user can call your API each day to avoid overload.

When you need to track which users are using your API and how much.

When you want to give different users different levels of access or limits.

When you want to protect your API from being used too much by a single user.

When you want to organize your API users and control their usage easily.

Commands

This command creates a new API key named 'my-api-key' and enables it so it can be used immediately.

Terminal

aws apigateway create-api-key --name my-api-key --enabled

Expected Output

{

    "id": "a1b2c3d4",

    "value": "xYz123AbCdEf456",

    "name": "my-api-key",

    "enabled": true

}

→

--name - Sets the name of the API key.

→

--enabled - Activates the API key immediately.

This command creates a usage plan named 'my-usage-plan' that limits users to 100 requests at once and 50 requests per second, with a total of 1000 requests allowed per day.

Terminal

aws apigateway create-usage-plan --name my-usage-plan --throttle burstLimit=100,rateLimit=50 --quota limit=1000,period=DAY

Expected Output

{

    "id": "u1v2w3x4",

    "name": "my-usage-plan",

    "throttle": {

        "burstLimit": 100,

        "rateLimit": 50.0

    },

    "quota": {

        "limit": 1000,

        "period": "DAY"

    }

}

→

--throttle - Sets the maximum burst and steady request rate.

→

--quota - Sets the total allowed requests in a time period.

This command links the API key 'a1b2c3d4' to the usage plan 'u1v2w3x4' so the key follows the usage limits.

Terminal

aws apigateway create-usage-plan-key --usage-plan-id u1v2w3x4 --key-id a1b2c3d4 --key-type API_KEY

Expected Output

{

    "id": "k1l2m3n4",

    "type": "API_KEY",

    "value": "xYz123AbCdEf456",

    "name": "my-api-key"

}

→

--usage-plan-id - Specifies which usage plan to link.

→

--key-id - Specifies which API key to link.

→

--key-type - Defines the type of key being linked.

This command lists all usage plans to verify the created plans and their settings.

Terminal

aws apigateway get-usage-plans

Expected Output

{

    "items": [

        {

            "id": "u1v2w3x4",

            "name": "my-usage-plan",

            "throttle": {

                "burstLimit": 100,

                "rateLimit": 50.0

            },

            "quota": {

                "limit": 1000,

                "period": "DAY"

            }

        }

    ]

}

Key Concept

If you remember nothing else from this pattern, remember: API keys identify users, and usage plans control how much each user can use your API.

Common Mistakes

Creating an API key but not linking it to a usage plan.

The API key will work but won't have any usage limits, risking overload.

Always link your API keys to a usage plan to enforce limits.

Setting usage plan limits too low or too high without testing.

Too low limits block legitimate users; too high limits fail to protect your API.

Start with reasonable limits and adjust based on real usage.

Not enabling the API key after creation.

Disabled keys cannot be used to access the API.

Use the --enabled flag when creating the API key or enable it later.

Summary

Create an API key to identify users of your API.

Create a usage plan to set limits on how much the API can be used.

Link the API key to the usage plan to apply those limits to the user.