The Complete Production SOP: How to Deploy and Run AWS API Gateway HTTP API (v2) & JWT Authorizers in Autonomous AI Agents
Step-by-step SOP to install and run aws-api-gateway-v2-http in Codex, Claude Code, and Cursor. Build serverless HTTP APIs with native JWT authentication.
Technical Overview & Architectural Context
When autonomous coding agents generate AWS API Gateway architectures, they frequently confuse v1 REST APIs with v2 HTTP APIs. This causes agents to generate deprecated swagger extensions, invoke custom Lambda authorizers unnecessarily instead of native RFC 6750 JWT authorizers, misconfigure CORS preflight handling on the $default stage, or assemble broken VPC link integrations that target network interfaces instead of private ALB/NLB listeners. Without strict architectural guardrails, agents emit high-latency configurations that incur excessive AWS costs and violate least-privilege zero-trust security postures. The aws-api-gateway-v2-http skill enforces deterministic SOP boundaries across Codex, Claude Code, Cursor, and Windsurf. It forces agents to utilize the AWS CLI v2 apigatewayv2 namespace or standard CloudFormation/Terraform AWS v2 constructs, explicitly configures OpenID Connect (OIDC) discovery endpoints with strict audience validation, correctly defines `$request.header.Authorization` identity sources, and configures declarative CORS policies directly on the gateway layer to avert 401 Unauthorized errors on OPTIONS preflights.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the SKILL.md definition into agent registry paths for dynamic runtime ingestion.
Autonomous agent runners scan `.agents/skills` or `.cursor/rules` to dynamically bind procedural rules. Placing the canonical SKILL.md specification inside the agent hierarchy guarantees triggers such as 'configure jwt authorizer api gateway' are parsed into the execution planner before code emission begins.
mkdir -p ~/.agents/skills/aws-api-gateway-v2-http && curl -fsSL https://askills.dev/api/skills/aws-api-gateway-v2-http/raw -o ~/.agents/skills/aws-api-gateway-v2-http/SKILL.md---
name: "aws-api-gateway-v2-http"
description: "Build low-latency, cost-effective serverless HTTP APIs with native JWT token authorization."
metadata:
author: "AWS"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "create api gateway v2 http api"
- "configure jwt authorizer api gateway"
- "setup api gateway vpc link"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# AWS API Gateway HTTP API (v2) & JWT Authorizers
Configures AWS API Gateway v2 (HTTP APIs): creating routes ($default, /api/{proxy+}), integrating Lambda and private VPC link backends, configuring JWT authorizers (Auth0, Cognito), and enabling CORS.Symlink `~/.agents/skills/aws-api-gateway-v2-http/SKILL.md` directly into `.cursor/rules/aws-apigw-v2.md` or `.windsurfrules` to eliminate context duplication across disparate IDE environments.
Ensure `shell_exec` is set to `false` in the manifest if you require the agent to generate Infrastructure as Code (IaC) templates rather than mutating real AWS infrastructure directly without human review.
Environment Secrets & Dependency Validation
Inject identity provider credentials and OIDC configurations safely without exposing secrets in chat transcripts.
Native JWT authorizers require the IdP Issuer URL and registered Client Audience IDs (e.g., from Cognito User Pools, Auth0, or Okta). These must be supplied via local configuration variables or environment files rather than plaintext tokens, enabling the agent to bind variables securely into Terraform or CloudFormation scripts.
cat << 'EOF' > .env.local
OIDC_ISSUER_URL="https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example"
OIDC_CLIENT_AUDIENCE="24g817g9abcdefghijklmn1234"
AWS_REGION="us-east-1"
EOFInstruct your agent to ingest issuer URLs and audience strings using Terraform variables (`var.jwt_issuer_url`) or AWS CloudFormation parameters rather than hardcoding production URIs.
Verify that `.env*` is matched in `.gitignore`. Never allow the agent to read live user JWT access tokens or AWS access keys directly into the LLM conversational context window.
Intent Matching & Trigger Invocation
Invoke the deterministic skill by executing prompts matched against declared frontmatter triggers.
Provide a structured prompt matching the triggers 'create api gateway v2 http api' and 'configure jwt authorizer api gateway'. The skill activates procedural compliance: validating that routes attach `AuthorizationType = 'JWT'`, setting `$request.header.Authorization` as the identity source, and implementing gateway-managed CORS.
Explicitly mention route paths (e.g., `GET /orders`, `POST /orders`, `$default`) in your prompt so the agent generates precise route keys rather than sloppy blanket wildcards.
If you use path-specific authorizers, ensure your agent does not apply the JWT authorizer to `OPTIONS /{proxy+}`, otherwise preflight requests from browser single-page applications will fail with HTTP 401.
Verification, Linting & Output Quality Gate
Execute automated infrastructure validation and syntax verification gates on generated configurations.
Before accepting changes, the agent must run validation scripts locally. For Terraform, this involves `terraform validate` and `tflint`; for CloudFormation/SAM, `cfn-lint` and `sam validate`. This guarantees generated API Gateway schemas do not contain missing integration bindings or malformed ARN references.
terraform fmt -check && terraform validateInstruct the agent to inspect the diff using `git diff --stat` and ensure generated route targets point to valid Lambda permissions (`aws_lambda_permission` with action `lambda:InvokeFunction`).
Omitting the Lambda invocation permission for API Gateway v2 (`Principal: apigateway.amazonaws.com`) will cause silent HTTP 500 execution failures upon deployment.
Real-World Scenario: Deploying an HTTP API with Auth0 JWT Authentication and Lambda Integration
“create api gateway v2 http api named 'ecommerce-orders-api' with CORS allowed for 'https://app.example.com'. configure jwt authorizer api gateway using Auth0 domain 'https://auth.example.com/' and audience 'https://api.example.com'. Add routes: GET /orders and POST /orders pointing to existing Lambda ARN 'arn:aws:lambda:us-east-1:123456789012:function:orders-service'. Emit clean Terraform.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent attached JWT authorization globally or omitted native API Gateway CORS configuration, causing browser preflight OPTIONS requests (which omit the Authorization bearer header) to be blocked by the authorizer.
cors_configuration {
allow_origins = ["https://app.example.com"]
allow_methods = ["GET", "POST", "OPTIONS"]
allow_headers = ["authorization", "content-type"]
max_age = 300
}
# Ensure routes do NOT require JWT on OPTIONS methods.Root Cause: The agent emitted an OIDC issuer domain without a trailing slash or missing the HTTPS scheme required by AWS API Gateway v2 OIDC discovery specification.
# Ensure issuer string ends with standard OIDC provider syntax
issuer = "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxxxxxx" # or "https://dev-xyz.auth0.com/"Frequently Asked Questions (AWS API Gateway HTTP API (v2) & JWT Authorizers SOP)
Q:Can I use AWS API Gateway HTTP API (v2) & JWT Authorizers across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. Once installed in `~/.agents/skills/aws-api-gateway-v2-http`, any compatible runtime (Codex, Claude Code, Cursor, Windsurf) parses the same triggers and SOP rules uniformly.
Q:How does AWS API Gateway HTTP API (v2) & JWT Authorizers prevent context window overflow during long agent sessions?
The skill establishes discrete procedural boundaries and precise syntax blueprints rather than dumping entire AWS documentation pages into prompt memory. By guiding the agent directly to v2 HTTP resources, it minimizes wasteful trial-and-error generation cycles.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100. It operates purely at the workspace file system level (`fs_read: true`, `fs_write: workspace`), requiring no shell execution (`shell_exec: false`) or direct live network privileges (`net_access: false`).
Ready to equip your autonomous agent with AWS API Gateway HTTP API (v2) & JWT Authorizers?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.