draft out rate limit details

[christinaausley]

Description

Closes https://github.com/camunda/developer-experience/issues/274.

When should this change go live?

• This change is not yet live and should not be merged until {ADD_DATE} (apply hold label or convert to draft PR)?
• There is no urgency with this change.
• This change or page is part of a marketing blog, conference talk, or something else on a schedule.
• This functionality is already available but undocumented.
• This is a bug fix or security concern.

PR Checklist

• I have added changes to the relevant /versioned_docs directory, or they are not for an already released version.
• I have added changes to the main /docs directory (aka /next/), or they are not for future versions.
• My changes require an Engineering review, and I've assigned an engineering manager or tech lead as a reviewer, or my changes do not require an Engineering review.
• My changes require a technical writer review, and I've assigned @christinaausley as a reviewer, or my changes do not require a technical writer review.

[christinaausley]

Will backport pending review 👍

[github-actions]

👋 🤖 ✅ Looks like the changes were ported across versions, nice job! 🎉

You can read more about the versioning within our docs in our documentation guidelines.

[daniel-ewing]

I made some changes. You might not like these changes. If you don't, then feel free to ignore me. For the last two lines, is there any way to indent the bullets (make a sub-bullet list):

The OAuth service has a built-in token request rate limit of about one request per second for all clients with the same source IP address.
The officially offered client libraries (as well as the NodeJS and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
If too many token requests are executed from the same source IP address in a short time, all token request from that source IP address are blocked for a certain time. Since an access token has a 24 hour validity period, it must be: cached on the client side, reused while still valid, refreshed via a new token request once its validity period has expired.
When the rate limit gets triggered, the client will receive an HTTP 429 response. Note the following workarounds:

• Cache the token as it is valid for 24 hours. The official SDKs already do this by default.
• Keep the SDK up to date. We have noted issues in older versions of the Java SDK which did not correctly cache the token.
• Given the rate limit applies to clients with the same source IP address, be mindful of:
  -- Unexpected clients running within your infrastructure.
  -- Updating all clients to use a current API key if you delete an API key and create a new one.

[christinaausley]

@daniel-ewing Adjusted based on your comment 👍

[multani]

I think it's also worth mentioning that all the requests are rate-limited, whether the request was successful or not.

It's especially important wrt. the last point you mentioned ("updating clients to use a new API key"): if a client can't authenticate because the credentials are expired and it "loops" trying to fetch a new token, its requests will count towards the rate limit.

I'm not sure what would be the best place to write this: maybe in the 3rd paragraph "if too many token requests are executed from the same source IP address in a short time"?

[multani]

I think it's also worth mentioning that all the requests are rate-limited, whether the request was successful or not.

It's especially important wrt. the last point you mentioned ("updating clients to use a new API key"): if a client can't authenticate because the credentials are expired and it "loops" trying to fetch a new token, its requests will count towards the rate limit.

@christinaausley do you have an idea also how to phrase this? This could also help support by pointing out to customers that problems on their side can affect themselves.

[daniel-ewing]

Hi @christinaausley, following up on @multani's comment, does anyone like this:

The OAuth service has a built-in token request rate limit of about one request per second for all clients with the same source IP address.

I don't know the markdown syntax for a warning box - make this part a warning:
All token requests count toward the rate limit, whether they are successful or not. If any client is running with an expired or invalid API key, that client will continually make token requests. That client will cause the rate limit to be exceeded for that IP address and it can block valid token requests from completing.

The officially offered ...

[christinaausley]

@daniel-ewing @multani thank you for your help here! Added a note 👍

[multani]

This looks great to me, thanks @christinaausley and @daniel-ewing !
@daniel-ewing do you think this will help Support team to redirect relevant support tickets to in the future?

[daniel-ewing]

@multani, I hope so! But if not, we tried...

adjusted in commit