# Add API Key Auth to a Serverless Framework API

Yes. An agent moves your Serverless Framework endpoints to API Gateway REST events with private: true, defines apiKeys and a usagePlan, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-api-key-auth/serverless/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads `serverless.yml` before changing an event. In a service shaped like `aws-node-rest-api-with-dynamodb` in serverless/examples, it declares `frameworkVersion: '4'`, `provider.runtime: nodejs24.x` on `arm64`, a `DYNAMODB_TABLE` environment variable built from the service and stage, and an IAM role statement for six DynamoDB actions on the table's ARN. Five functions, `create`, `list`, `get`, `update` and `delete`, each have one `httpApi` event on `/todos` or `/todos/{id}`, and `resources` defines the `TodosDynamoDbTable` with `PAY_PER_REQUEST` billing. The handlers in `todos/*.js` are ES modules (`"type": "module"` in `package.json`) using `@aws-sdk/lib-dynamodb` v3, reading `event.body` and `event.pathParameters.id`. Nothing restricts who can call them.

`httpApi` is API Gateway's HTTP API, and HTTP APIs have no API keys or usage plans; their options are JWT authorizers, Lambda authorizers and IAM. API keys with quotas and throttling are a REST API feature, exposed in the framework through `http` events with `private: true` and an `apiGateway.apiKeys` list under `provider`, which is how two services in the same repository do it: `aws-node-typescript-apollo-lambda` sets `apiGateway.apiKeys` with a name and a value from `${env:APOLLO_LAMBDA_KEY, ...}` and marks its `http` events `private: true`, and `aws-node-dynamic-image-resizer` does the same. The agent follows that pattern because the question asks for keys, and says in the pull request that a Lambda authorizer on the HTTP API is the alternative if the team wants to stay on HTTP API.

So it changes each of the five events from `httpApi` to `http` with the same `path` and `method`, adds `private: true` to all five, and adds `cors: true` because REST events do not get the HTTP API's default CORS. Under `provider.apiGateway` it adds `apiKeys` with one key named from the service and stage, value from `${env:TODOS_API_KEY}` with no default so a deploy without the variable fails loudly rather than shipping a known key, and a `usagePlan` with `quota` and `throttle` values the prompt sets. The handler code does not change: REST API v1 events also carry `body` and `pathParameters.id`, and the `statusCode`/`body` return shape is the same. It updates `README.md`, whose `curl` lines must now send `-H 'x-api-key: ...'` and whose endpoint URLs gain the stage segment that REST APIs have.

Framework v4 needs a Serverless access key even to package, so the agent reads `SERVERLESS_ACCESS_KEY` from the Project's secrets when one is there, runs `npm install` and `serverless package`, and reads the compiled `cloudformation-template-update-stack.json` in `.serverless/` to confirm the `AWS::ApiGateway::ApiKey`, `AWS::ApiGateway::UsagePlan` and `UsagePlanKey` resources and `ApiKeyRequired: true` on each method. Without the secret it cannot package and says so, checking the YAML against the two in-repo examples instead. It does not deploy: there are no AWS credentials in the sandbox and the pull request says that too.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add API key authentication to this Serverless Framework service and open a pull request. Read serverless.yml, package.json, every file under todos/ and README.md first, and look at how other services in the repository use apiGateway.apiKeys and private: true if any do. Because HTTP API events have no API keys or usage plans, change each httpApi event to an http event with the same path and method, add private: true and cors: true to each, add provider.apiGateway.apiKeys with one key whose value comes from the TODOS_API_KEY environment variable with no default, and a usagePlan with a quota of 10000 requests per month and a throttle of 50 burst and 20 rate. Leave the handlers unchanged. Update README.md so the curl examples send x-api-key and show the stage segment REST API URLs have. If SERVERLESS_ACCESS_KEY is available, run npm install and serverless package and quote the ApiKey, UsagePlan, UsagePlanKey resources and ApiKeyRequired settings from the compiled template in .serverless; if it is not, say so. Do not deploy. In the pull request, explain the move from HTTP API to REST API and name the Lambda authorizer alternative.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request that changes `serverless.yml` (five event blocks, a `provider.apiGateway` section with `apiKeys` and `usagePlan`) and `README.md`, with no change to `todos/*.js` or `package.json`. The description explains the HTTP API to REST API move, lists the new URL shape with its stage segment, and, when packaging ran, quotes the `AWS::ApiGateway::ApiKey`, `UsagePlan` and `UsagePlanKey` resources and the `ApiKeyRequired: true` on each method from the compiled template.

The examples repository has no workflow that deploys a service, so the quoted template is the check. A team with a `serverless deploy` workflow on pull requests will see the deploy need `TODOS_API_KEY` set in that environment, which the pull request calls out.

A reviewer checks that the key value has no default, that the quota and throttle match the plan they sell, that `cors: true` is wanted now that the HTTP API's CORS defaults are gone, and that every client is told the new URL and the `x-api-key` header. After merge, `serverless deploy` prints the key value once in its output.

## Run it on every service going public

A team that exposes several Serverless Framework services sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own `serverless.yml`, so a service already on `http` events only gains `private: true` and the key section, and each opens its own pull request. Start the session in a Project that holds `SERVERLESS_ACCESS_KEY` as a secret, with `POST /o/{org}/p/{project}/sessions`, so every run can package. A `request_id` in the body makes a retry safe.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends with the `session_url`, so the usage plan settings across services can be compared before anything is deployed.

## Why run it on Rush?

The wrong answer here is quick and plausible: an `apiKeys` block added under a service that uses `httpApi`, which deploys without error and protects nothing, because HTTP APIs ignore it. In a Rush sandbox the agent packages the service with the real framework and reads the compiled CloudFormation for `ApiKeyRequired` on every method, and that template stays in the run's record beside the diff, so the reviewer sees the resources that will be created rather than YAML that looks right.

It also reads the repository's own examples for the established pattern and writes down the trade the change makes, HTTP API features for REST API keys, so the decision is explicit in the pull request. The same request works unchanged on the next service, each in its own sandbox.

## Frequently asked questions

### Why move from httpApi to http events?

Because API keys and usage plans exist only on API Gateway REST APIs. HTTP API events offer JWT authorizers, Lambda authorizers and IAM instead. If you want to stay on HTTP API, the agent can add a Lambda request authorizer that checks `x-api-key` against a stored value; the pull request names that alternative.

### Do the handlers change?

No. Both API types pass `body` and `pathParameters` and accept the same `statusCode` and `body` return shape, so `todos/*.js` is untouched. The visible differences are the URL, which gains a stage segment such as `/dev`, and the header clients must send.

### Where does the key value come from?

From `TODOS_API_KEY` in the environment at deploy time, with no default, so a deploy without it fails instead of creating a key with a value committed to the repository. `serverless deploy` prints the created key once; clients send it as `x-api-key`.

### Does the agent deploy anything?

No. With a `SERVERLESS_ACCESS_KEY` secret in the Project it runs `serverless package` and quotes the compiled template; without one it says packaging was not possible. Deploying needs AWS credentials and is left to your pipeline.

## More Serverless Framework jobs

- [Add CloudWatch Alarms to a Serverless Framework Service](https://getrush.ai/run/add-cloudwatch-alarms/serverless/)
- [Add CORS to a Serverless Framework API from a Linear Issue](https://getrush.ai/run/add-cors/serverless/)
- [Add Cursor Pagination to a Serverless DynamoDB API](https://getrush.ai/run/add-cursor-pagination/serverless/)

## The same job on other stacks

- [Add API Key Authentication to a Slim 4 App](https://getrush.ai/run/add-api-key-auth/slim/)
- [Add API Key Authentication to a FastAPI App on SQLModel](https://getrush.ai/run/add-api-key-auth/sqlmodel/)
- [Add API Key Authentication to a Cloudflare Worker API](https://getrush.ai/run/add-api-key-auth/cloudflare-workers/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
