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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add API Key Authentication to a Slim 4 App (Slim)
- Add API Key Authentication to a FastAPI App on SQLModel (SQLModel)
- Add API Key Authentication to a Cloudflare Worker API (Cloudflare Workers)