Feat/custom rate limit policies by nick-gagliardi · Pull Request #1252 · auth0/docs-v2

nick-gagliardi · 2026-05-21T20:22:25Z

Description

Adds a new documentation page explaining custom rate limit policies, which let customers set per-application request ceilings on the Authentication API to protect tenants from misconfigured or misbehaving applications.

What's covered

How custom rate limits relate to tenant-level rate limits
Policy evaluation hierarchy (Client ID → Group → Global/Default)
Pooled counters (Group policies) vs independent counters (Global/Default policies)
Which Authentication API requests count toward custom limits and which are excluded
Log-only mode for validating limits before enforcement
Guidance on choosing rate limit values for first-party and third-party applications
Step-by-step Dashboard instructions for creating each policy type
Monitoring via tenant logs and HTTP response headers (Auth0-RateLimit, X-RateLimit-*)

References

Testing

Checklist

I've read and followed CONTRIBUTING.md.
I've tested the site build for this change locally.
I've made appropriate docs updates for any code or config changes.
I've coordinated with the Product Docs and/or Docs Management team about non-trivial changes.

github-actions · 2026-05-21T20:27:28Z

Summary

Status	Count
🔍 Total	5
✅ Successful	0
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	5
❓ Unknown	0
🚫 Errors	0
⛔ Unsupported	0
Full Github Actions output

mintlify · 2026-05-21T20:30:00Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
auth0	🟢 Ready	View Preview	May 21, 2026, 8:43 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

- Add Auth0-RateLimit structured header documentation - Move throttling behavior under Monitor policy enforcement - Add 5 missing endpoints to counted requests table - Add Retry-After header and JSON error body details - Document /authorize 302 redirect behavior on rate limit - Clarify Default policy bucket isolation - Add once-per-minute log sampling detail - Add "Block an application entirely" subsection

avanscoy · 2026-05-28T16:51:38Z

+description: Set per-application rate limit ceilings to protect your tenant from misconfigured or misbehaving applications.
+---
+
+Custom rate limit policies let you set per-application request ceilings on your tenant's Authentication API. When an application calls Auth0 (requesting tokens, starting authorization flows, or refreshing credentials) each request counts toward that application's configured limit. If an application exceeds its ceiling due to a bug, retry loop, or unexpected behavior, Auth0 throttles it before it can consume your tenant's shared rate limit capacity.


Suggested change

Custom rate limit policies let you set per-application request ceilings on your tenant's Authentication API. When an application calls Auth0 (requesting tokens, starting authorization flows, or refreshing credentials) each request counts toward that application's configured limit. If an application exceeds its ceiling due to a bug, retry loop, or unexpected behavior, Auth0 throttles it before it can consume your tenant's shared rate limit capacity.

Custom rate limit policies let you set per-application request ceilings on your tenant's calls to [Authentication API](https://auth0.com/docs/api/authentication). When an application calls Auth0 (requesting tokens, starting authorization flows, or refreshing credentials) each request counts toward that application's configured limit. If an application exceeds its ceiling due to a bug, retry loop, or unexpected behavior, Auth0 throttles it before it can consume your tenant's shared rate limit capacity.

avanscoy · 2026-05-28T17:13:56Z

+
+### Pooled counters (Group policies)
+
+Group policies use a single shared counter for all applications in the group. Every request from any group member draws from the same bucket.


Suggested change

Group policies use a single shared counter for all applications in the group. Every request from any group member draws from the same bucket.

Group policies use a single, shared counter for all applications in the group. Every request from any group member draws from the same bucket.

avanscoy · 2026-05-28T17:16:04Z

+
+Group policies use a single shared counter for all applications in the group. Every request from any group member draws from the same bucket.
+
+For example, if you create a Group policy called "Third-Party Clients" with a limit of 100 RPS, and the group contains five applications, the 100 RPS limit applies to their combined traffic. If one application sends 90 RPS and the others send 5 RPS each, the group has hit its limit (90 + 5 + 5 + 5 + 5 = 110 RPS) and subsequent requests from any application in the group are throttled. There is no guaranteed allocation per application within the group.


Suggested change

For example, if you create a Group policy called "Third-Party Clients" with a limit of 100 RPS, and the group contains five applications, the 100 RPS limit applies to their combined traffic. If one application sends 90 RPS and the others send 5 RPS each, the group has hit its limit (90 + 5 + 5 + 5 + 5 = 110 RPS) and subsequent requests from any application in the group are throttled. There is no guaranteed allocation per application within the group.

For example, if you create a Group policy called "Third-Party Clients" with a limit of 100 RPS, and the group contains five applications, the 100 RPS limit applies to their combined traffic. If one application sends 90 RPS and the others send 5 RPS each, the group hits its limit (90 + 5 + 5 + 5 + 5 = 110 RPS). Auth0 throttles subsequent requests from any application in the group. There is no guaranteed allocation per application within the group.

avanscoy · 2026-05-28T17:18:31Z

+| Passkey challenge | `/passkey/challenge` | Back-channel call to initiate a passkey authentication challenge. |
+| Passkey registration | `/passkey/register` | Back-channel call to register a new passkey. |
+
+## Requests excluded from custom rate limits


Suggested change

## Requests excluded from custom rate limits

## Custom rate limit exclusions

avanscoy · 2026-05-28T17:19:29Z

+
+<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
+
+Because browser-initiated requests are excluded, custom rate limit policies reduce but do not eliminate the risk of attacks that exhaust tenant-wide rate limits by triggering complete authentication flows. For protection against those attack patterns, see [Attack Protection](/docs/secure/attack-protection).


Suggested change

Because browser-initiated requests are excluded, custom rate limit policies reduce but do not eliminate the risk of attacks that exhaust tenant-wide rate limits by triggering complete authentication flows. For protection against those attack patterns, see [Attack Protection](/docs/secure/attack-protection).

Because browser-initiated requests are excluded, custom rate limit policies reduce but do not eliminate the risk of attacks that exhaust tenant-wide rate limits by triggering complete authentication flows. For protection against those attack patterns, read [Attack Protection](/docs/secure/attack-protection).

…ate-limit-policy/custom-rate-limit-policies.mdx Co-authored-by: Amanda VS <amanda.vanscoy@auth0.com>

nick-gagliardi requested a review from a team as a code owner May 21, 2026 20:22

custom rate limit policies first draft

2b72d5d

nick-gagliardi force-pushed the feat/custom-rate-limit-policies branch from b74ba98 to 2b72d5d Compare May 21, 2026 20:26

mintlify Bot deployed to staging - main May 21, 2026 20:39 View deployment

mintlify Bot deployed to staging - main May 21, 2026 20:43 View deployment

nick-gagliardi force-pushed the feat/custom-rate-limit-policies branch from d09d265 to 7bece03 Compare May 22, 2026 15:48

mintlify Bot deployed to staging - main May 22, 2026 16:17 View deployment

mintlify Bot deployed to staging - main May 22, 2026 16:24 View deployment

Update custom-rate-limit-policies.mdx

74bbc21

mintlify Bot deployed to staging - main May 22, 2026 16:51 View deployment

nick-gagliardi added 2 commits May 26, 2026 10:37

updating per meeting with brian

7a62929

updating per meeting with brian

7e3b56f

mintlify Bot deployed to staging - main May 26, 2026 14:43 View deployment

clarifying x-rate-limit header ambiguity

f85e506

mintlify Bot deployed to staging - main May 26, 2026 15:02 View deployment

Update custom-rate-limit-policies.mdx

544069f

mintlify Bot deployed to staging - main May 26, 2026 18:59 View deployment

updating with review fixes

463938e

mintlify Bot deployed to staging - main May 28, 2026 15:07 View deployment

Update custom-rate-limit-policies.mdx

0a60572

mintlify Bot deployed to staging - main May 28, 2026 15:16 View deployment

avanscoy reviewed May 28, 2026

View reviewed changes

Comment thread ...shoot/customer-support/operational-policies/rate-limit-policy/custom-rate-limit-policies.mdx Outdated

avanscoy reviewed May 28, 2026

View reviewed changes

Comment thread ...shoot/customer-support/operational-policies/rate-limit-policy/custom-rate-limit-policies.mdx Outdated

avanscoy reviewed May 28, 2026

View reviewed changes

nick-gagliardi and others added 2 commits May 28, 2026 13:21

Update main/docs/troubleshoot/customer-support/operational-policies/r…

cc2a30e

…ate-limit-policy/custom-rate-limit-policies.mdx Co-authored-by: Amanda VS <amanda.vanscoy@auth0.com>

Update main/docs/troubleshoot/customer-support/operational-policies/r…

9b1294b

…ate-limit-policy/custom-rate-limit-policies.mdx Co-authored-by: Amanda VS <amanda.vanscoy@auth0.com>

mintlify Bot deployed to staging - main May 28, 2026 17:23 View deployment

mintlify Bot deployed to staging - main May 28, 2026 17:25 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat/custom rate limit policies#1252

Feat/custom rate limit policies#1252
nick-gagliardi wants to merge 11 commits into
mainfrom
feat/custom-rate-limit-policies

nick-gagliardi commented May 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 21, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented May 21, 2026 •

edited

Loading

Uh oh!

avanscoy May 28, 2026

Uh oh!

Uh oh!

Uh oh!

avanscoy May 28, 2026

Uh oh!

avanscoy May 28, 2026

Uh oh!

avanscoy May 28, 2026

Uh oh!

avanscoy May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		### Pooled counters (Group policies)

		Group policies use a single shared counter for all applications in the group. Every request from any group member draws from the same bucket.

	Group policies use a single shared counter for all applications in the group. Every request from any group member draws from the same bucket.
	Group policies use a single, shared counter for all applications in the group. Every request from any group member draws from the same bucket.


		Group policies use a single shared counter for all applications in the group. Every request from any group member draws from the same bucket.

		For example, if you create a Group policy called "Third-Party Clients" with a limit of 100 RPS, and the group contains five applications, the 100 RPS limit applies to their combined traffic. If one application sends 90 RPS and the others send 5 RPS each, the group has hit its limit (90 + 5 + 5 + 5 + 5 = 110 RPS) and subsequent requests from any application in the group are throttled. There is no guaranteed allocation per application within the group.

	## Requests excluded from custom rate limits
	## Custom rate limit exclusions


		<Callout icon="file-lines" color="#0EA5E9" iconType="regular">

		Because browser-initiated requests are excluded, custom rate limit policies reduce but do not eliminate the risk of attacks that exhaust tenant-wide rate limits by triggering complete authentication flows. For protection against those attack patterns, see [Attack Protection](/docs/secure/attack-protection).

Conversation

nick-gagliardi commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

References

Testing

Checklist

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

mintlify Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

avanscoy May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

avanscoy May 28, 2026

Choose a reason for hiding this comment

Uh oh!

avanscoy May 28, 2026

Choose a reason for hiding this comment

Uh oh!

avanscoy May 28, 2026

Choose a reason for hiding this comment

Uh oh!

avanscoy May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nick-gagliardi commented May 21, 2026 •

edited

Loading

github-actions Bot commented May 21, 2026 •

edited

Loading

mintlify Bot commented May 21, 2026 •

edited

Loading