Modes

Unkey offers fixed window rate limiting out of the box for all API keys. This means that you can set a limit on how many requests a key can make in a given time window. If the limit is exceeded, the key will be blocked from making further requests until the window resets.

We provide 2 ways of rate limiting, optimized for different usecases.

​

Local, fast rate limiting at the edge

API key validation is very sensitive to latency because it is in the critical path of your application. Therefore minimizing the latency impact of rate limiting is a key priority.

Rate limiting at the edge comes with no latency increase and effectively rate limits your users at each edge location. To make this possible, each edge location maintains their own rate limiting and updates with the global state asynchronously, thus a user could exceed your rate limit if they go through different edge locations.

This way of limiting is effective to protect your application because there is a guaranteed upper bound after all edge locations the user is accessing have reached their limit.

​

Example

curl --request POST \
  --url https://api.unkey.dev/v1/keys.createKey \
  --header 'Authorization: Bearer <UNKEY>' \
  --header 'Content-Type: application/json' \
  --data '{
	"apiId":"<API_ID>",
	"prefix":"xyz",
	"byteLength":16,
	"ownerId":"<USER_ID>",
	"ratelimit":{
		"async": true, // edge rate limiting
		"limit": 10,
		"duration": 1000
	}
}'

​

Global consensus rate limiting

If having a strict rate limit that must not be exceeded, even when verifying keys in multiple regions, is required, then this is a good option.

This way of limiting is guaranteed to be consistent globally, but it comes with a higher latency impact.

Typically most of your traffic should pass, and we recommend using the local rate limiting to provide a better user experience and only use global rate limiting when you really need to.

​

Example

curl --request POST \
  --url https://api.unkey.dev/v1/keys.createKey \
  --header 'Authorization: Bearer <UNKEY>' \
  --header 'Content-Type: application/json' \
  --data '{
	"apiId":"<API_ID>",
	"prefix":"xyz",
	"byteLength":16,
	"ownerId":"<USER_ID>",
	"ratelimit":{
		"async": false, // origin rate limiting
		"limit":10,
		"duration": 1000
	}
}'