-
Notifications
You must be signed in to change notification settings - Fork 1.8k
docs: rate limits table with search #2460
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
unatasha8
wants to merge
35
commits into
master
Choose a base branch
from
feat/rate-limits-table-with-search
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 29 commits
Commits
Show all changes
35 commits
Select commit
Hold shift + click to select a range
248b689
feat: add rate limits table with search option
wassimoo 3aa2fc0
docs: update content around new rate limit tables
unatasha8 02a61ee
docs: make format updates
unatasha8 3e3fbd4
docs: fixed formating issues
unatasha8 f2d8218
docs: fix formatting
unatasha8 0b45fcd
docs: update terminology in RateLimitsTable component
wassimoo 8b8c258
docs: added old rate limit page back, broke up new rate limit pages i…
unatasha8 732be49
docs: update bucket naming 'threshold' definitions
unatasha8 019afda
refactor: update rate limit CSV files and adjust filter component styles
wassimoo 9c2231b
chore: format rate-limits.json
wassimoo 9f88387
docs: updated structure of rate limit files and added communication c…
unatasha8 3be4bf1
feat: filter out hidden methods
wassimoo e2b30c8
docs: updated plugins
unatasha8 b5a5203
docs: updated with feedback
unatasha8 32a7d82
docs: make format fixes
unatasha8 4eba387
docs: Moved project rate limit content from high-level 'new' to 'proj…
unatasha8 26317be
chore: vendor rate-limit CSVs without date-stamped filenames
tricky42 2323b19
Merge branch 'master' into feat/rate-limits-table-with-search
wassimoo 986b944
chore: update dependencies in package-lock.json and package.json
wassimoo 7838ac2
docs: added rate limit pages to sidebar file
unatasha8 b3effaa
Merge branch 'master' into feat/rate-limits-table-with-search
wassimoo e30a9d5
refactor: move RateLimitsTable import to its single usage site
wassimoo 02f7a44
fix: run format
wassimoo 347c431
chore: update bucket-to-endpoints.csv
tricky42 45a9dec
docs(rate-limits): align messaging with new rate limit blog post
tricky42 3628e3a
chore: run format
tricky42 9b5c4bd
Merge branch 'master' into feat/rate-limits-table-with-search
tricky42 3a1c7e7
docs(rate-limits): fix keto bucket example and drop self-referencing …
tricky42 b5d56db
chore: remove trailing comments
wassimoo 2a58d02
docs: added load-performance-testing to sidebar
unatasha8 a898ce0
docs: removing sidebar-old.ts
unatasha8 d93b9fa
Merge branch 'master' into feat/rate-limits-table-with-search
wassimoo 44d4ef9
Merge branch 'master' into feat/rate-limits-table-with-search
wassimoo d51f09a
docs: fixed .sh instances on rate limit pages
unatasha8 5fdb2bc
docs: updated launch dates schedule
unatasha8 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| id: load-performance-testing | ||
| title: Load and performance testing | ||
| sidebar_label: Load and performance testing | ||
| --- | ||
|
|
||
| Load testing, stress testing, and performance testing against Ory Network require prior written approval. Unauthorized load | ||
| testing may be detected as abusive traffic and result in temporary blocking of your project or IP addresses. | ||
|
|
||
| For eligibility, request procedures, and requirements, see the | ||
| [Load Testing Policy](https://www.ory.sh/legal/load-testing-policy). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| --- | ||
| id: rate-limits-endpoint | ||
| title: Endpoint rate limits for Ory Network | ||
| sidebar_label: Endpoint rate limits | ||
| --- | ||
|
|
||
| Endpoint-based rate limits apply to individual API endpoints regardless of your project rate limits. They protect specific | ||
| endpoints against brute-force and credential stuffing attacks, which typically originate from a limited set of IP addresses or JA4 | ||
| fingerprints. | ||
|
|
||
| Benefits: | ||
|
|
||
| - Enhanced security—Restricts requests from specific sources, making attacks significantly harder to succeed | ||
| - Bot protection—Differentiates genuine users from harmful automated activity | ||
| - Granular control—Fine-tunes security for individual endpoints without compromising user experience | ||
|
|
||
| ## Types of endpoint-based protection | ||
|
|
||
| Ory implements two types of endpoint-based protection: | ||
|
|
||
| - **Volumetric**: Limits the total amount of traffic over time. | ||
| - **Inflight**: Limits the number of concurrent active requests. | ||
|
|
||
| ### Volumetric rate limits | ||
|
|
||
| Volumetric rate limits analyze incoming request patterns based on: | ||
|
|
||
| - Source identification—IP addresses and JA3/JA4 fingerprints | ||
| - Request frequency—Detects volumetric attacks and system overwhelm attempts | ||
| - Authentication status—Different limits for authenticated vs. unauthenticated requests | ||
| - HTTP method—Varying limits based on GET, POST, etc. | ||
|
|
||
| ### Inflight rate limits | ||
|
|
||
| Inflight rate limits protect critical endpoints from concurrent request attacks. By preventing multiple requests to the same | ||
| resource at once, they eliminate race conditions, ensure data consistency, and let critical operations complete safely. | ||
|
|
||
| The following endpoints are protected by rate limits. | ||
|
|
||
| | Type | Endpoint | HTTP Methods | Ratelimit Key | Action: enforced vs report-only | | ||
| | :------- | :------------------------------------------ | :----------------------- | :----------------------------------------------- | :------------------------------------- | | ||
| | Inflight | `/admin/identities` | `POST`, `PATCH` | `{project_id} + {full_path}` | Blocks concurrent requests (enforced) | | ||
| | Inflight | `/admin/identities/{id}` | `PUT`, `PATCH`, `DELETE` | `{project_id} + {full_path}` | Blocks concurrent requests (enforced) | | ||
| | Inflight | `/admin/identities/{id}/credentials/{type}` | `DELETE` | `{project_id} + {full_path}` | Blocks concurrent requests (enforced) | | ||
| | Inflight | `/admin/identities/{id}/sessions` | `DELETE` | `{project_id} + {full_path}` | Blocks concurrent requests (enforced) | | ||
| | Inflight | `/admin/sessions/{id}` | `DELETE` | `{project_id} + {full_path}` | Logs concurrent requests (report-only) | | ||
| | Inflight | `/admin/sessions/{id}/extend` | `PATCH` | `{project_id} + {full_path}` | Logs concurrent requests (report-only) | | ||
| | Inflight | `/self-service/recovery` | `POST` | `{project_id} + {path} + "/" + {email\|flow_id}` | Logs concurrent requests (report-only) | | ||
|
|
||
| :::note | ||
|
|
||
| Enforced-endpoints return HTTP 429 when the rate limit is exceeded. Report-only-endpoints currently only log rate limit | ||
| violations; they don't block requests. GET, OPTIONS, and HEAD requests are exempt from rate limiting. | ||
|
|
||
| ::: | ||
|
|
||
| ### Configuration and rule management | ||
|
|
||
| The endpoint-based rate limit rules are set and managed by Ory. These rules aren't directly configurable by customers. |
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,111 @@ | ||
| --- | ||
| id: rate-limits-new | ||
| title: Ory Network rate limits - new | ||
| sidebar_label: Rate limits - New | ||
| --- | ||
|
|
||
| :::info | ||
|
|
||
| There is a new project rate limit policy, which applies to all new Ory Network customers and to existing customers after they've | ||
| been migrated. If you're an existing customer and haven't received a migration notice yet, see the | ||
| [rate limits - legacy](/docs/guides/rate-limits-legacy). See [Rate limits](/docs/guides/rate-limits) to learn about both policies | ||
| and the migration plan. Endpoint-based rate limits have not changed. | ||
|
|
||
| ::: | ||
|
|
||
| Ory uses rate limits to protect your applications against abuse, attacks, and service disruptions, and to maintain fair resource | ||
| allocation and network stability. | ||
|
|
||
| ## Types of rate limits | ||
|
|
||
| Ory uses two types of rate limits: | ||
|
|
||
| - **Project rate limits**: Control the overall request volume your projects can make to Ory APIs, based on your subscription tier | ||
| and project environment. See [Project rate limits](./rate-limits-project) for more information. | ||
| - **Endpoint-based rate limits**: Control traffic to individual endpoints to protect against volumetric attacks, brute-force | ||
| attempts, and concurrent request abuse—regardless of your project rate limits. See | ||
| [Endpoint-based rate limits](./rate-limits-endpoint) for more information. | ||
|
|
||
| ## Monitor rate limit headers | ||
|
|
||
| Ory Network includes rate limit information in API response headers. Use these headers to avoid exceeding the applicable rate | ||
| limit. Your client must handle these responses to maintain service quality. | ||
|
|
||
| | Header | Description | | ||
| | ----------------------- | --------------------------------------------------------------------------------------- | | ||
| | `x-ratelimit-limit` | The rate limit ceiling(s) for the current request, including burst and sustained limits | | ||
| | `x-ratelimit-remaining` | Number of requests remaining in the current window | | ||
| | `x-ratelimit-reset` | Number of seconds until the rate limit window resets | | ||
|
|
||
| Example header values: | ||
|
|
||
| ```shell | ||
| x-ratelimit-limit: 10, 10;w=1, 300;w=60 | ||
| x-ratelimit-remaining: 8 | ||
| x-ratelimit-reset: 1 | ||
| ``` | ||
|
|
||
| The `x-ratelimit-limit` header follows the | ||
| [IETF RateLimit header fields draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/), where `w=1` | ||
| indicates a 1-second window and `w=60` indicates a 60-second window. Use these headers to throttle requests proactively and reduce | ||
| the likelihood of hitting 429 errors. | ||
|
|
||
| ## How to handle 429 responses | ||
|
|
||
| When your client receives a `429 Too Many Requests` response, you've exceeded the applicable rate limit. Your client must handle | ||
| these responses to maintain service quality. | ||
|
|
||
| Your implementation must: | ||
|
|
||
| - **Detect 429 responses**: Monitor for HTTP 429 status codes on all API calls. | ||
| - **Back off before retrying**: Prefer the server's `x-ratelimit-reset` header when available; fall back to exponential backoff | ||
| capped at 30 seconds. Always add jitter so concurrent clients don't retry in lockstep. | ||
| - **Throttle proactively**: Check `x-ratelimit-remaining` and `x-ratelimit-reset` to slow down before you hit a 429. | ||
| - **Avoid retry storms**: Don't retry failed requests in a tight loop. | ||
|
|
||
| ### Exponential backoff strategy | ||
|
|
||
| When a request returns `429`, back off before retrying. Prefer the server's `x-ratelimit-reset` header when it's present, fall | ||
| back to exponential backoff capped at 30 seconds otherwise, and always add jitter so concurrent clients don't retry in lockstep. | ||
|
|
||
| ```jsx | ||
| async function callApiWithBackoff(request, maxRetries = 5) { | ||
| for (let attempt = 0; attempt < maxRetries; attempt++) { | ||
| const response = await fetch(request) | ||
| if (response.status !== 429) return response | ||
|
|
||
| const resetAfter = response.headers.get("x-ratelimit-reset") | ||
| const baseDelay = resetAfter ? parseInt(resetAfter, 10) * 1000 : Math.min(Math.pow(2, attempt) * 1000, 30000) // cap at 30s | ||
|
|
||
| const jitter = Math.random() * 1000 | ||
| await new Promise((resolve) => setTimeout(resolve, baseDelay + jitter)) | ||
| } | ||
| throw new Error("Max retries exceeded") | ||
| } | ||
| ``` | ||
|
|
||
| You can also throttle proactively using `x-ratelimit-remaining` to slow down before hitting a 429: | ||
|
|
||
| ```jsx | ||
| async function callApiWithThrottle(request) { | ||
| const response = await fetch(request) | ||
| const remaining = parseInt(response.headers.get("x-ratelimit-remaining"), 10) | ||
| const resetIn = parseInt(response.headers.get("x-ratelimit-reset"), 10) | ||
|
|
||
| if (remaining < 5 && resetIn > 0) { | ||
| const paceDelay = (resetIn * 1000) / Math.max(remaining, 1) | ||
| await new Promise((resolve) => setTimeout(resolve, paceDelay)) | ||
| } | ||
| return response | ||
| } | ||
| ``` | ||
|
|
||
| Clients that repeatedly exceed rate limits without proper backoff may have their API access temporarily blocked. For high-volume | ||
| use cases that exceed your plan's limits, open a support ticket via the [Ory Console](https://console.ory.sh/support) or email | ||
| [support@ory.sh](mailto:support@ory.sh). | ||
|
|
||
| ## Load testing | ||
|
|
||
| Load testing against the Ory Network requires prior written approval. Unauthorized tests will be detected and may result in | ||
| temporary blocking. To request an approved window, open a support ticket via the [Ory Console](https://console.ory.sh/support) or | ||
| email [support@ory.sh](mailto:support@ory.sh). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| --- | ||
| id: rate-limits-project | ||
| title: Project rate limits | ||
| sidebar_label: Project rate limits | ||
| --- | ||
|
|
||
| import RateLimitsTable from "@site/src/components/RateLimitsTable" | ||
|
|
||
| Each project has a set of rate limit buckets. A bucket is a named group of API endpoints that share the same rate limit threshold. | ||
| When a request comes in, Ory resolves which bucket the endpoint belongs to and applies the threshold for that bucket. | ||
|
|
||
| Bucket thresholds are determined by two factors: | ||
|
|
||
| - **Subscription tier**: The project's subscription tier (Developer, Production, Growth, or Enterprise). | ||
| - **Project environment**: The project's environment (Production, Staging, or Development). | ||
|
|
||
| For a detailed explanation of tiers and environments, see our [Workspaces and environments guide](/docs/guides/workspaces). | ||
|
|
||
| ## Rate limits per bucket | ||
|
|
||
| Buckets follow a `{service}-{access}-{threshold}` naming pattern. For example: | ||
|
|
||
| - `kratos-public-high`: for endpoints with a high rate limit allowance | ||
| - `hydra-public-medium`: for endpoints with a moderate rate limit allowance | ||
| - `hydra-admin-low`: for endpoints with a low rate limit allowance | ||
|
|
||
| :::info | ||
|
|
||
| A bucket counter is shared across all endpoints in the same bucket. For example, `PUT /admin/relation-tuples` and | ||
| `DELETE /admin/relation-tuples` both belong to `keto-admin-low`, so every call to either endpoint counts against the same limit. | ||
| Plan your request volumes accordingly. | ||
|
|
||
| ::: | ||
|
|
||
| You will see two rate limits for each bucket: | ||
|
|
||
| - **Burst limit**: Maximum requests per second (rps), allowing for short traffic spikes. | ||
| - **Sustained limit**: Maximum requests per minute (rpm), ensuring consistent performance over time. | ||
|
|
||
|
unatasha8 marked this conversation as resolved.
|
||
| ## Identify the rate limits that apply to your project | ||
|
|
||
| In the **Project rate limit table** below: | ||
|
|
||
| 1. Select your subscription tier from the **Tier** dropdown. Options are Developer, Production, Growth, or Enterprise. | ||
| 2. Select your project environment from the **Environment** dropdown. Options are Production, Staging, or Development. | ||
| 3. To search by API path, enter the API path into the **Search API path** box. The endpoint appears highlighted. Look to see which | ||
| bucket it belongs to for its rate limit. | ||
|
|
||
| ### Project rate limit table | ||
|
|
||
| <RateLimitsTable /> | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.