AI Agent - Aug 8, 2026

AgentCore Rate Limits with OAuth and IAM Dimensions

Quick answer

Choose an AgentCore Gateway rate-limit dimension that represents the resource allocation you actually want to protect.

  • Use a stable JWT role, team, or tier claim for a shared group bucket.
  • Add JWT sub when each user needs an isolated bucket.
  • Use $.context.iam.principal or $.context.iam.sourceIdentity for IAM-authenticated callers.
  • Combine identity with targetName, toolName, or qualifiedModelId when the limit should apply to one downstream surface.

Avoid unbounded identifiers. Always decide what unmatched traffic should receive and add a wildcard catch-all when it must remain under customer-defined enforcement.

Supported dimension families

FamilyAWS-documented keysTypical use
TargettargetName, toolName, qualifiedModelIdbackend, tool, or model capacity
OAuth / JWT$.context.jwt.<claim>user, role, team, or service buckets
IAM$.context.iam.principal, $.context.iam.sourceIdentityIAM caller or original source identity

The presence of a claim does not make it a good bucket key. Confirm it is stable, trusted, bounded, and populated consistently for every request path.

Group, user, and hybrid buckets

A role-only bucket is shared by everyone with that role. It can protect allocation between tiers, but one user can consume the group’s entire capacity. A subject-only bucket isolates individuals but does not impose a combined ceiling on the group.

Layer both when you need both outcomes. AWS says matching rate limits are independently enforced with AND semantics, so the request must have capacity in both buckets.

Hybrid dimensions answer narrower questions:

  • role plus target: how much of one backend a group may consume;
  • subject plus target: how much of a backend one user may consume;
  • role plus tool: how frequently a group may call a sensitive tool;
  • role plus model plus subject: per-user model allocation inside a tier.

Entry matching and wildcard order

Specific dimension values take precedence over *. A wildcard value does not create one shared bucket for all unmatched values; AWS says each distinct resolved value receives its own independent bucket at the wildcard entry’s rate.

In multi-dimension entries, * is trailing-only: after a wildcard appears, subsequent dimensions must also be wildcards. Dimension-key order therefore affects which fallback patterns can be represented. AWS also says the same dimension-key set cannot be duplicated in a different order on the same Gateway.

Document the ordered key list as part of the configuration contract rather than treating it as formatting.

Avoid cardinality traps

Claims such as jti, nonce, or request ID can create a new bucket for nearly every request. That defeats fairness and can reduce the effectiveness of rate limiting. Prefer bounded claims such as:

  • account tier;
  • role;
  • team;
  • stable subject;
  • stable agent identity;
  • named target, tool, or model.

Monitor the number of observed bucket values and alert when a supposedly bounded dimension grows unexpectedly.

Rate limits run before Policy

AgentCore rate limiting is evaluated before AgentCore Policy. A request that Policy denies can consume the rate bucket first. AWS recommends explicit zero-rate entries for users or groups that should be blocked at the rate layer, while keeping Policy as the authorization source of truth.

This ordering also means rate limits cannot prove that a caller is authorized. AWS documents fail-open evaluation, so authentication, AgentCore Policy, WAF, and tool-side checks remain separate controls.

Frequently asked questions

Which identity dimensions does AgentCore Gateway support for rate limits?

AWS documents JWT claims through $.context.jwt.<claim>, plus $.context.iam.principal and $.context.iam.sourceIdentity for IAM-based traffic.

Which target dimensions are supported?

AWS documents targetName, toolName, and qualifiedModelId as target-side dimensions.

What does a wildcard entry do?

The * value acts as a catch-all and gives each distinct resolved value its own bucket at that entry’s rate. Without a matching catch-all, traffic can bypass that customer-defined limit.

Which JWT claims should not be used as dimensions?

Avoid high-cardinality or unbounded claims such as nonce, jti, or request IDs. Prefer stable bounded identifiers such as subject, role, team, or tier.

Official sources

Source check: August 8, 2026. Verify current claim paths, matching rules, dimensions, quotas, and enforcement behavior against AWS documentation and your identity provider.