Please refer to this FAQ for questions regarding rate limits for Okta Workforce Identity Cloud (WIC) and Customer Identity Solutions (CIS).
Table of Contents
General Understanding
What are rate limits?
Why did Okta implement rate limits?
What information is included in rate limit headers?
What are burst rate limits?
Managing Rate Limits
How can customers check their current rate limit status?
How are customers notified when they are approaching their rate limit?
How can customers check historical rate limit usage?
What happens when customers exceed their rate limits, and how should customers handle rate limit errors?
How can customers optimize their applications to stay within the rate limits?
How does rate limiting affect an application’s performance?
Does rate limiting apply differently across different regions or countries?
I have a planned significant activity that is expected to breach the rate limits for a few APIs. How can I manage this activity
without impacting performance?
I think I need higher rate limits because the default rate limits are not enough. What process should I follow to enable this
in my tenant?
Documentation and Resources
Where can I find detailed documentation on the rate limits for each API endpoint?
General Understanding
What are rate limits?
Rate limiting is a mechanism that controls the rate at which requests can be made to use Okta’s services, thereby preventing the flooding of resources, ensuring fair usage, and preventing denial-of-service attacks and other malicious activities. By applying rate limits across our public-facing endpoints, Okta is able to control usage across all customers and tenants. Okta uses a fixed-window algorithm for rate limiting.
Apart from a set of Okta APIs that are subject to rate limits, there are several other types of rate limits that Okta applies on its platform. For more details, please refer to the Product Documentation.
Customers are encouraged to use their org’s rate limit dashboard as the source of truth to verify the rate limit settings for an API name.
Why did Okta implement rate limits?
Rate limiting is a standard practice in the SaaS industry, used by a variety of providers and vendors to ensure optimal performance and availability of their services. This feature is not unique to Okta but rather an industry-wide practice to promote service stability and reliability.
-
- Maintain quality of service. By limiting the number of requests over a given time period, rate limiting mitigates the impact of abusive behavior, protects against failures, and encourages efficient and scalable use of resources.
- Ensure fair usage. Equitable resource allocation ensures that no single organization or user monopolizes system resources, allowing fair access for all. Rate limiting also prevents abuse by limiting the ability of malicious users to create flood requests that could degrade service for others.
- Protect our infrastructure. Rate limiting helps maintain a balanced load distribution of requests while managing sudden spikes in traffic. Limiting the rate of incoming requests also helps mitigate the impact of accidental or unintentional request floods.
What information is included in rate limit headers?
When making API requests, Okta returns certain headers that provide information about the current rate limit status:
-
- X-Rate-Limit-Limit - the rate limit ceiling that is applicable for the current request.
- X-Rate-Limit-Remaining - the number of requests left for the current rate limit window.
- X-Rate-Limit-Reset - the time at which the rate limit resets, specified in UTC epoch time.
For example, if an API endpoint has the following rate limit:
Rate limit: 1000 requests per minute
If you receive the following x-headers in your API response:
-
- X-Rate-Limit-Limit: 1000
- X-Rate-Limit-Remaining: 0
- X-Rate-Limit-Reset: 1731007800
You now know that:
-
- Your tenant has used up 1000 out of the 1000 requests allowable for that API, and has 0 requests remaining for the rate limiting window.
- Any new requests made within this fixed time window will be rejected because the requests have exceeded the rate limit.
- New requests can be made at or after 1731007800, or 7:30:00 PM UTC on November 7, 2024, when the rate limit resets.
What are burst rate limits?
Okta introduced burst rate limits as a benefit to customers by providing an additional allowance for request rates that breach the default endpoint rate limits. This feature helps mitigate the risk of unplanned traffic spikes impacting the user experience. Burst rate limits are active by default on authentication and authorization endpoints only.
In a scenario where an organization exceeds the default rate limit for a burst-enabled endpoint, the org will receive a warning and a burst notification. A burst buffer is applied at this point. A violation will occur when the burst rate threshold is breached, resulting in the consequences described below.
In this burst rate limiting example, the base (default) threshold is 1000 while the burst rate is set at 5X the base rate or 5000.
The x-headers in the API response when a burst rate limit is applied will have the following values:
-
- X-Rate-Limit-Limit: 1000
- X-Rate-Limit-Remaining: 1
- X-Rate-Limit-Reset: 1731007800
Note: Burst rate limits are not guaranteed and are dependent on system capacity at a given point in time. Customers consistently finding themselves using burst rate limits should consider purchasing DynamicScale to mitigate the risk of service disruption.
Managing Rate Limits
How can customers check their current rate limit status?
- Admin Console Widget. Okta provides a Rate Limit Monitoring Widget in the Admin Console to allow administrators to track rate limit warning and violations over the last 24hrs or the last 7 days. Clicking into any listed violations or selecting View will take the administrator to the rate limit dashboard.
- Rate Limit Dashboard. Okta provides a dashboard from the Admin Console to help administrators proactively monitor their rate limit consumptions and investigate potential rate limit issues.
- Rate Limiting HTTP Response Headers. Okta provides three headers (X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset) to report on rate limits. Relevant headers in the response can be checked to monitor rate limits.
- Notifications. Okta provides notifications via Okta System logs and email notifications to system administrators when the warning, burst rate, and violation thresholds are breached. A banner warning will also be displayed on the Okta admin console. Event hooks can also be used to actively monitor and respond to notifications.
How are customers notified when they are approaching their rate limit?
- SysLog, Widget & Email Notifications. By default, a warning threshold of 60% is set for all applicable APIs. A Warning Notification is generated when the warning threshold is exceeded. Warnings appear as a generated System Log event, an entry on the Rate Limit Monitoring Widget in the Admin console, and as an email notification to Okta Super Administrators. Similarly, when a violation occurs, a Violation Notification is generated through the same channels.
- Rate Limit Dashboard Notifications. All rate limit notifications on System Log (warnings, violations, and bursts) will also be listed with links on the rate limit dashboard.
- Custom Notifications. Okta recommends that customers make use of event hooks to proactively monitor rate limit warnings and violations. A typical use case would be a workflow event trigger that generates a notification on an integrated messaging platform such as Slack.
How can customers check historical rate limit usage?
System log data is retained on the Okta platform for up to 3 months, and can be used to review rate limit-related log events over this period. All Events (warnings, bursts, violations) on the rate limit dashboard can also be segmented into the last 24hrs, last 7 days, last month, or the last 3 months. Clicking into an API name on the rate limit dashboard provides a detailed, per-minute view of usage for up to the last 8 days.
What happens when customers exceed their rate limits, and how should customers handle rate limit errors?
If a defined rate limit is exceeded, Okta returns a “HTTP 429 Too Many Requests” status code, and the processing of all further requests will be stopped up until the reset time. If using an API, the header response will include X-Rate-Limit-Reset, which tells the client how long to wait before making another request. Customers will also receive a warning and violation event notifications through the notification touchpoints described above. Depending on the API, a customer may also receive a burst rate limit applied notification prior to receiving a violation notification.
Customers are encouraged to implement techniques for optimally managing retry attempts. Retry logic with exponential backoff is an example of such an algorithm - in this scenario, when a rate limit is hit, the client waits for a progressively longer period before retrying the request. This approach reduces the risk of continually hitting the limit by ensuring that the X-Rate-Limit-Reset header is honored, and allows time for the window to reset.
How can customers optimize their applications to stay within the rate limits?
- Okta recommends using best practices to optimize API calls by techniques such as caching responses, creating batch job requests, using exponential backoff, and minimizing redundant calls.
- API caching stores copies of API responses to speed up future requests and reduces the need to fetch data repeatedly, thus improving the overall performance. Customers can, for instance, implement client-side caching by temporarily storing data on a user’s device.
- Customers can also make use of the limit query parameter for individual API endpoints that support this function. The number of requests per API endpoint can be reduced by increasing the default limit value to its maximum setting.
- For example, HTTP GET request for the following API /api/v1/logs is set to a default value of 100. For customers with high log volumes, Okta recommends increasing the default setting to its maximum value (1000). More information can be found here.
- Customers are also encouraged to make use of client-based rate limiting where applicable. When client-based rate limiting is enabled, requests from each client can be tracked and limited to an assigned rate limit. More information can be found here.
Note that frequent violations by the same APIs are an indicator that appropriate caching and redundancy measures are not in place on the application side. In such cases, Okta recommends that customers review and adapt their design in line with the suggested best practices.
How does rate limiting affect an application’s performance?
If an application exceeds the rate limit, it will receive a 429 error response and will not be able to send any additional requests to that specific endpoint until the reset time. This could potentially create a disruptive experience for other apps and users that depend on a reliable interaction with Okta. To ensure fair and equitable access across applications, Okta offers token and application rate limits that can be used to govern how much of an organization-wide rate limit a token or app can consume. It is important to implement proper handling of these responses to maintain a good user experience.
Does rate limiting apply differently across different regions or countries?
No.
I have a planned significant activity that is expected to breach the rate limits for a few APIs. How can I manage this activity without impacting performance?
In cases where the planned activity is a controlled API event to load or process data, customers are advised to follow Okta’s best practices for managing rate limits. Customers are expected to comply with the default rate limits, and ensure that request rates are controlled within the expected ranges.
In cases where the planned activity has significantly less control (e.g. a marketing event where end user impact is difficult to predict), Okta recommends that customers reach out to Okta for assistance. Such planned and infrequent activities are good examples of use cases where a temporary rate limit increase may be justified. It is however recommended that customers carefully review the business justifications for the increase. Please follow the rate limit increase request process here, and ensure that the request is received at least 15 business days before the event.
I think I need higher rate limits because the default rate limits are not enough. What process should I follow to enable this in my tenant?
Customers that require rate limit increases have 2 options:
-
- For temporary requests:
- If customers find that the default rate limits do not meet their needs, they can request a temporary rate limit increase from Okta. Such requests are evaluated based on the use case and business justification. Customers are encouraged to use evidence from historical use cases or data (e.g. violation events from last year’s thanksgiving sale) to support the business justification. The process for requesting a temporary rate limit increase can be found here. Requests must be received at least 15 business days before the required start date of the increased rate limit. Each request is evaluated independently. Approval of a previous request does not guarantee a future approval. In the process of maintaining service levels, Okta may raise or lower limits without notice. Okta reserves the right to rate limit other functionality to prevent abuse, spam, denial-of-service attacks, or other security issues.
- For permanent requests:
- CIS Customers:
- For CIS customers who require higher rate limits for authentication and authorizations endpoints only, the DynamicScale add-on service can be purchased per organization. DynamicScale increases the default rate limits up to 1000 times depending on the tier multiplier purchased. This add-on can be purchased for either production or preview organizations. DynamicScale is only applicable to a subset of authentication and authorization endpoints. Customers can review the API name on their org’s rate limit dashboard to verify their DynamicScale setting.
- For any other endpoints, CIS customers can submit a rate limit increase request through the process described here. A detailed use case and business justification for why a temporary rate limit is not an option will need to be made. Each request is evaluated independently and approvals are not guaranteed. Approval of a previous request does not guarantee future approval. Okta assesses the impact of each request on system performance and available capacity at the time of submission.
- WIC Customers:
- For WIC Customers, a Workforce Multiplier is applied to their organization based on the volume of Universal Directory licenses purchased. Workforce Multipliers only grant higher rate limits for authentication and authorization endpoints. More information on Workforce Multipliers can be found here.
- If rate limit increases for Workforce Multiplier endpoints or any other endpoints are required, this can be requested via the rate limit increase request process described here. A detailed use case and business justification for why a temporary rate limit is not an option will need to be made. Each request is evaluated independently and approvals are not guaranteed. Approval of a previous request does not guarantee future approval. Okta assesses the impact of each request on system performance and available capacity at the time of submission.
- CIS Customers:
- For temporary requests:
Note that if continued requests for temporary increases are made for endpoints covered by DynamicScale, Okta may deny the request and require customers to consult the account team to explore purchasing DynamicScale.
