AWS API Gateway (REST)

EntryGuard integrates with AWS API Gateway REST APIs by managing a dedicated statement inside the API's resource policy. When users start sessions, their IP is added to the aws:SourceIp condition on that statement; when they stop, it is removed.

HTTP APIs not supported

Resource policies only exist on REST APIs (v1). HTTP APIs (v2) rely on authorizers and route-level IAM for access control and are not supported by this integration. If you need EntryGuard in front of an HTTP API, put an AWS WAFv2 IP Set in front of it and configure that instead.

How it works

EntryGuard owns a single dedicated statement in the resource policy, identified by a stable Sid:

{
  "Sid": "EntryGuardWhitelist",
  "Effect": "Allow",
  "Principal": "*",
  "Action": "execute-api:Invoke",
  "Resource": "arn:aws:execute-api:<region>:*:<apiId>/*/*/*",
  "Condition": {
    "IpAddress": {
      "aws:SourceIp": ["1.2.3.4/32", "2001:db8::1/128"]
    }
  }
}

• Any other statements in your policy (e.g. VPC-endpoint restrictions, IAM allow-lists, deny rules) are preserved untouched. EntryGuard only reads, updates, or removes its own Sid.
• The aws:SourceIp list holds both IPv4 and IPv6 CIDRs in the same array — no separate dual-stack pairing needed like AWS WAFv2 IP Sets.
• When the last CIDR is revoked, EntryGuard removes the whole statement so your policy stays minimal when no sessions are active.

Prerequisites

• The REST API must already exist. EntryGuard does not create APIs.

• The IAM credential attached to the resource needs the following permissions on the target API:

  Action	Purpose
  apigateway:GET on arn:aws:apigateway:<region>::/restapis/<apiId>*	Read current resource policy
  apigateway:PATCH on arn:aws:apigateway:<region>::/restapis/<apiId>*	Umbrella permission for any PATCH on this API resource
  apigateway:UpdateRestApiPolicy on arn:aws:apigateway:<region>::/restapis/<apiId>*	Specific carve-out required to mutate the /policy field
  apigateway:POST on arn:aws:apigateway:<region>::/restapis/<apiId>*	Trigger CreateDeployment to propagate policy changes to the target stage

  The wildcard-suffix ARN (.../restapis/<apiId>*) covers both the API itself and its /deployments sub-resource in one statement.

  Why the mix of verb-based and fine-grained actions

  API Gateway's IAM uses HTTP-verb-based action names for almost all operations (apigateway:GET, apigateway:POST, apigateway:PATCH, etc.). Updating an API's resource policy is a defense-in-depth check that requires both the umbrella apigateway:PATCH and the fine-grained apigateway:UpdateRestApiPolicy. AWS carved the fine-grained action out specifically so admins can grant apigateway:PATCH on an API for general edits (name, description) while separately controlling who can change who can invoke it.

  The IAM Policy Generator page in the EntryGuard dashboard will emit these scoped exactly for the APIs you register. See AWS IAM Policy.

• If your API already has other policy statements you want to keep, add them before connecting to EntryGuard. EntryGuard preserves anything with a different Sid, but a policy that has never been set from the console won't exist yet.

Adding an API Gateway resource

1. Go to Resources → Add Resource.

2. Provider → AWS, Resource Type → API Gateway (REST).

3. Resource Identifier → the REST API ID (found under API Gateway → APIs in the AWS console — a short string like abc123def4).

4. Region → the API's region.

5. Config:

   Field	Required?	Default	Notes
   sid	optional	EntryGuardWhitelist	Statement Sid we manage. Change this if you already use EntryGuardWhitelist for something else.
   action	optional	execute-api:Invoke	Rarely needs changing.
   resourceArn	optional	arn:aws:execute-api:<region>:*:<apiId>/*/*/*	Restrict the statement to a specific stage or method by overriding here (e.g. .../prod/GET/*).
   deploymentStageName	recommended	(unset)	Name of the stage EntryGuard should redeploy after each policy update. See Stage redeployment below.

6. Click Create, then Verify capacity. A green tick means EntryGuard can read and write the policy.

Stage redeployment

AWS API Gateway caches resource policies per stage. Per AWS documentation:

After you create or update a REST API resource policy, you must deploy the API for the policy to take effect on that stage.

In practice, changes usually propagate within a minute or two, but the docs are authoritative — until a stage is redeployed, the previous policy may still be enforced.

EntryGuard handles this for you when deploymentStageName is set on the resource config. After every successful apply/revoke, EntryGuard calls CreateDeployment on that stage so the policy change is immediately effective.

If you do not set deploymentStageName, EntryGuard writes the policy and stops there. The change will still take effect once API Gateway's stage cache refreshes, but there's a short window (seconds to a minute) where the old policy is enforced. For most use cases the recommendation is to set the stage name.

If CreateDeployment fails (missing IAM permission, stage doesn't exist, etc.) the apply/revoke itself still succeeds — the policy write was already committed and the change will take effect on the next stage cache refresh. The failure is logged for investigation.

Debouncing during bursty session activity

Users starting and stopping sessions in quick succession (e.g. VPN hopping) can generate many policy updates per minute on the same API. AWS's control-plane rate limits (5 rps steady account-wide, and a per-API CreateDeployment soft throttle around 1 per 5s) make firing a deployment on every single apply/revoke both wasteful and risky — you'd blow the account cap that legitimate customer automation also relies on.

EntryGuard debounces CreateDeployment per (apiId, stageName): at most one deployment every 30 seconds for the same stage, regardless of how many session events fire in between. The policy write itself is never debounced — it always runs. So a burst of 60 session events in a minute produces 60 policy updates and at most 2 deployments.

If your usage genuinely needs sub-30-second propagation (rare for a whitelisting tool), you can rely on API Gateway's natural stage cache refresh, which typically picks up policy changes within ~60 seconds without any deployment.

Reading the policy after setup

Once EntryGuard has applied its first CIDR, you can inspect the policy in the AWS console:

API Gateway → APIs → your-api → Resource Policy

You should see:

• Your existing statements (if any), unchanged.
• A new statement with Sid: EntryGuardWhitelist containing the whitelisted CIDRs of all currently active sessions.

Removing the integration

To fully detach EntryGuard from an API Gateway resource without breaking your other statements:

1. In EntryGuard, stop all active sessions that touch the API.
2. Confirm the EntryGuardWhitelist statement is empty (it will be auto-removed once the last CIDR is revoked).
3. Delete the API Gateway resource in EntryGuard.

Your other policy statements remain intact.

Troubleshooting

Policy update fails with an "invalid policy document" error. Usually means a hand-edited statement in your policy is malformed. EntryGuard only mutates its own Sid, but AWS revalidates the entire document on every update. Fix the offending statement in the AWS console first.

Resource verification fails with "API Gateway REST API not found". Check the API ID is correct and the region matches. If the credential was recently rotated, verify the credential first.

Access-denied errors on apply/revoke. The credential's IAM policy is missing apigateway:GET or apigateway:PATCH scoped to your API's ARN. Regenerate the IAM policy from the IAM Policy Generator page and re-attach it.