How do I configure per-key rate limits in Unkey so they’re enforced during key verification?

Configuring per-key rate limits in Unkey lets you control exactly how often each API key can call your backend, with the limits enforced automatically every time a key is verified. This keeps abuse in check, protects downstream services, and ensures fair usage across tenants or customers—without you having to build your own rate‑limiting infrastructure.

Below is a practical guide to setting up per-key rate limits in Unkey so they’re enforced as part of the key verification flow.

---

How Unkey’s per-key rate limiting works

Unkey’s rate limiting is:

• Global and edge-enforced – Limits are applied as close to your users as possible for low latency and high reliability.
• Per identifier – You can rate limit per IP, per user, per API key, or any custom identifier that matters to you.
• Configured per customer / key – Different keys can have different limits, which is essential for tiered plans or internal vs public keys.
• Integrated into key verification – When enabled, rate limits are checked and enforced during the key verification step, so you don’t have to call a separate rate limiting service.

At a high level, your app will:

1. Receive an API key from the client.
2. Call Unkey to verify the key.
3. Let Unkey apply per-key rate limits during that verification.
4. Decide to allow or deny the request based on the verification and rate limit result.

---

Choosing your rate limit strategy

Before configuring Unkey, decide how you want to scope your limits:

• Per API key (most common)
  Each key has its own rate limit (e.g., 1000 requests/min per key). Ideal for SaaS plans where each customer has their own key.

• Per user + key
  Combine an internal user ID with the key for more granularity (e.g., user-123:key-abc).

• Per IP address
  Useful for public APIs where users may not be authenticated but you still need to throttle abusive IPs.

Unkey supports all of these patterns with its “per IP, per user, per API key, or any identifier” rate limiting model.

---

Step 1: Create or identify the API key you want to rate limit

You can manage keys using Unkey’s dashboard or API.

• In the dashboard, go to your project and open the Keys tab.
• Create a new key or select an existing key.
• Note the Key ID or the key’s external identifier; you’ll use it as the rate limit subject.

You’ll typically have one key per customer, service, or environment.

---

Step 2: Decide per-key rate limit values

For each key (or key tier), define:

• Requests per interval – e.g., 100, 1000, or 10_000
• Interval duration – e.g., 1s, 60s, 1m, 1h

Examples:

• Free plan: 100 requests / minute per key
• Pro plan: 1000 requests / minute per key
• Internal service: unlimited or very high thresholds

These values can be:

• Stored in your database and attached to the key as metadata, or
• Configured directly via Unkey’s API if per-key configuration is supported in your plan.

---

Step 3: Configure per-key rate limits in Unkey

Unkey’s rate limiting is designed to be simple and configurable. At configuration time you define how Unkey should interpret and enforce limits:

• Per API key – The key itself is the identifier.
• Custom identifier – A concatenation of key and user ID, or any custom string.

Typical configuration options include:

• limit – Maximum number of requests allowed in the time window.
• interval – Time window length, expressed in milliseconds or a human-readable string.
• identifier – What to rate limit on (e.g., key, ip, userId, or a custom value).

Depending on your environment, you’ll either:

• Use Unkey’s dashboard to set a default rate limit per workspace, per tenant, or per key group, or
• Use Unkey’s REST API to create/update rate limits programmatically for each key.

Because Unkey supports “custom configuration per customer,” you can store different limit/interval values per key and have them enforced automatically during verification.

---

Step 4: Enforce rate limiting during key verification

To have rate limits enforced as part of key verification, your server should:

1. Extract the API key from the request (e.g., from Authorization header).
2. Call Unkey’s verification API/SDK, passing the key and optional identifier metadata.
3. Check the verification response to see whether:
   • The key is valid.
   • The request has exceeded the configured rate limit.

Below is a conceptual example using TypeScript and the Unkey SDK:

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"]!,
});

export async function handleRequest(req: Request) {
  const apiKey = req.headers.get("Authorization")?.replace("Bearer ", "");
  if (!apiKey) {
    return new Response("Missing API key", { status: 401 });
  }

  // Optionally derive a custom identifier (e.g., per user or IP)
  const clientIp = req.headers.get("x-forwarded-for") ?? "unknown";

  const verification = await unkey.keys.verify({
    key: apiKey,
    // Optional: attach metadata for more granular rate limiting
    // identifier: clientIp, userId, or combined string
  });

  if (!verification.valid) {
    return new Response("Invalid API key", { status: 401 });
  }

  // At this point Unkey has:
  // - Verified the key
  // - Applied per-key (or per-identifier) rate limits on the edge

  if (verification.rateLimit?.limited) {
    // The key has hit its configured limit
    return new Response("Rate limit exceeded", {
      status: 429,
      headers: {
        "Retry-After": verification.rateLimit.retryAfter.toString(),
      },
    });
  }

  // Optionally, use analytics usage from the verification result
  // verification.usage, verification.rateLimit.remaining, etc.

  // Continue with your application logic
  return new Response("OK", { status: 200 });
}

Key points:

• Single verification call: You don’t need a separate “check rate limit” API call; Unkey’s global rate limiting is applied as part of verification.
• Per-key logic: Unkey can apply different limits per customer or per key based on your configuration.
• Fast and global: Enforcement happens on the edge for low latency.

---

Step 5: Use real-time analytics to monitor per-key limits

Once per-key rate limits are configured and enforced during verification, use Unkey’s Realtime Analytics to:

• See how often each key is being used.
• Identify keys that frequently hit rate limits.
• Spot abnormal spikes that might indicate abuse or misconfiguration.

From the dashboard, for any key you can inspect:

• Usage over the last 30 days
• Total uses
• Last used time
• Whether requests were successful, rate limited, or exceeded usage

This view is useful when tuning per-key limits or upgrading customers to higher tiers.

---

Step 6: Tune per-key limits over time

As your traffic grows, adjust per-key rate limits based on real usage:

• Raise limits for high-value or internal keys to prevent unnecessary throttling.
• Lower limits for noisy keys that risk overloading your downstream systems.
• Introduce tiered plans (free, pro, enterprise), each mapped to different per-key rate limit configurations.

Because permission and configuration changes are propagated globally in seconds, updates to rate limits take effect quickly across all regions.

---

Best practices for per-key rate limiting in Unkey

• Always validate first: Treat key verification + rate limiting as the first step of your request pipeline.
• Use meaningful identifiers: If per IP isn’t enough, combine identifiers like userId:keyId for more control.
• Return clear errors: Respond with 429 Too Many Requests when limited and include Retry-After so clients can back off.
• Leverage multi-cloud and edge: Let Unkey’s multi-cloud, edge-enforced rate limiting handle global traffic surges instead of building your own distributed limiter.
• Integrate with RBAC: Pair per-key limits with Unkey’s role-based access control so each key has both correct permissions and appropriate quotas.

---

By configuring Unkey’s per-key rate limits and enforcing them during key verification, you get a robust, low-latency throttle directly at the edge. This approach keeps your APIs responsive and secure while giving you fine-grained control over how every key— and every customer—uses your platform.