Rate limiting

Unkey offers token-bucket rate limiting out of the box for all API keys. You only need to specify the total number of tokens as well as the refill rate.

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 minimal performance penalties (around 0.1ms) and effectively rate limits your users at each edge location. To make this possible, each edge location maintains their own rate limiting, 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":{
		"type":"fast",
		"limit":10,
		"refillRate": 1,
		"refillInterval": 1000
	}
}'

​

Global consensus rate limiting

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

Be aware that this can add significant latency to your application, because all ratelimit operations need to go through a single service, which is currently running in us-east-1.

​

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":{
		"type":"consistent",
		"limit":10,
		"refillRate": 1,
		"refillInterval": 1000
	}
}'