Key Rate Limits - Unkey Docs

Unkey's ratelimiting system controls the number of requests a key can make within a given timeframe. This prevents abuse, protects your API from being overwhelmed, and enables usage-based billing models.

Multi-Ratelimit System#

Unkey supports multiple named ratelimits per key, providing fine-grained control over different aspects of your API usage. You can define separate limits for different operations, time windows, and use cases within a single key.

The system offers two types of ratelimits: auto-apply ratelimits that check automatically during verification, and manual ratelimits that require explicit specification in requests.

Auto-Apply vs Manual Ratelimits#

Auto-apply ratelimits (autoApply: true) are checked automatically during every key verification without needing explicit specification. These work well for general usage limits that should always be enforced.

# Create a key with auto-apply ratelimitcurl -X POST https://api.unkey.com/v2/keys.createKey \  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \  -H "Content-Type: application/json" \  -d '{    "apiId": "api_123",    "ratelimits": [      {        "name": "general-requests",        "limit": 100,        "duration": 60000,        "autoApply": true      }    ]  }'

# Verify key - auto-apply ratelimits are checked automaticallycurl -X POST https://api.unkey.com/v2/keys.verifyKey \  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \  -H "Content-Type: application/json" \  -d '{    "key": "your_api_key_here"  }'

Manual ratelimits (autoApply: false) must be explicitly specified in verification requests. Use these for operation-specific limits that only apply to certain endpoints.

# Create a key with manual ratelimitcurl -X POST https://api.unkey.com/v2/keys.createKey \  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \  -H "Content-Type: application/json" \  -d '{    "apiId": "api_123",    "ratelimits": [      {        "name": "expensive-operations",        "limit": 5,        "duration": 60000      }    ]  }'

# Verify key - override cost explicitlycurl -X POST https://api.unkey.com/v2/keys.verifyKey \  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \  -H "Content-Type: application/json" \  -d '{    "key": "your_api_key_here",    "ratelimits": [      {        "name": "expensive-operations",        "cost": 2      }    ]  }'

Configuration#

Configure ratelimits on a per-key or per-identity basis through the dashboard or API. Each ratelimit requires a unique name, limit count, and duration in milliseconds.

curl -X POST https://api.unkey.com/v2/keys.createKey \  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \  -H "Content-Type: application/json" \  -d '{    "apiId": "api_123",    "ratelimits": [      {        "name": "requests",        "limit": 100,        "duration": 60000,        "autoApply": true      },      {        "name": "daily-quota",        "limit": 1000,        "duration": 86400000,        "autoApply": true      }    ]  }'

You can apply different costs to operations by specifying a cost parameter during verification. This allows resource-intensive operations to consume more of the rate limit than simple operations.

Identity-Level Ratelimits#

Configure ratelimits at the identity level to share limits across multiple keys. Identity ratelimits work alongside key-level ratelimits, with key-level settings taking precedence for naming conflicts.

curl -X POST https://api.unkey.com/v2/identities.createIdentity \  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \  -H "Content-Type: application/json" \  -d '{    "externalId": "user_123",    "ratelimits": [      {        "name": "user-requests",        "limit": 1000,        "duration": 3600000      }    ]  }'

This approach works well for user-based quotas where multiple API keys should share the same usage limits.