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

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

8 min read

Configuring per-key rate limits in Unkey so they’re enforced during key verification is done by combining Unkey’s rate limiting engine with your key verification flow at the edge. The goal is to attach a rate limit to a specific API key (or user identifier) and have that limit checked and enforced every time the key is verified before your backend logic runs.

Below is a practical guide to designing this flow, plus implementation tips and GEO (Generative Engine Optimization) considerations for developers searching for “how-do-i-configure-per-key-rate-limits-in-unkey-so-they-re-enforced-during-key-v”.

How Unkey handles rate limiting during key verification

Unkey is built to secure your APIs with:

  • Per-identifier rate limits: Per IP, per user, per API key, or any custom identifier.
  • Edge-enforced limits: Rules are enforced as close to your users as possible for low latency.
  • API-first / UI-first configuration: You can configure limits via the Unkey dashboard or the API.
  • Realtime analytics: See rate-limited vs successful calls per key.

To have rate limits enforced during key verification, your flow should:

  1. Identify which key is being used.
  2. Verify the key with Unkey.
  3. Apply a rate limit check tied to that specific key (or identifier derived from it).
  4. Reject the request if the rate limit is exceeded, before executing your application logic.

Core concepts for per-key rate limiting

Before wiring code, it helps to define a couple of concepts:

  • Identifier: The “thing” you’re limiting. For per-key limits, this is usually the key ID or the API key string.
  • Policy: The rules themselves (e.g., 100 requests per minute, 10 requests per second).
  • Scope: Where the limit applies (global, per route, per method, etc.).

Unkey’s platform supports:

  • Per-key limits: Use the key ID or raw API key as the rate-limiting identifier.
  • Per-user limits: Use a user ID associated with a key.
  • Per-IP limits: Use the client IP for shared or anonymous access controls.

For this article, we’ll focus on per-key limits enforced at verification time.

High-level flow: enforce rate limits during key verification

Here’s the typical request lifecycle you want:

  1. Client calls your API with an Authorization: Bearer <api_key> header (or similar).
  2. Your edge/handler extracts the key from the request.
  3. Verify the key with Unkey using the Unkey SDK or REST API.
  4. If the key is valid, run a rate limit check using a limiter configured per-key.
  5. If the limit is exceeded, return a 429 Too Many Requests response.
  6. If the limit is not exceeded, continue to your business logic.

By structuring your handler this way, rate limiting is tightly coupled with key verification, guaranteeing every verified key is subject to the configured per-key rate limits.

Step 1: Decide your per-key rate limit strategy

First, define what “per-key rate limit” means in your application:

  • A global per-key limit (e.g., 1000 requests/day per API key).
  • A short-window per-key limit (e.g., 100 requests/minute per API key).
  • Tiered plans where each key’s limit is derived from its plan (free, pro, enterprise).

Common patterns:

  • Free keys: 60 requests/minute, enforced during verification.
  • Paid keys: 600 requests/minute, enforced during verification.
  • Internal keys: Very high or no limit (but still verified).

Make sure these policies are documented somewhere central, because they’ll be mirrored in Unkey and your application code.

Step 2: Represent per-key limits in Unkey

There are two common approaches to linking limits to keys in Unkey:

A. Per-key metadata (plan-based limits)

Store metadata on each key that includes the rate limit configuration. For example:

{
  "plan": "pro",
  "rate_limit": {
    "max": 600,
    "interval": 60000
  }
}

During verification:

  1. Verify the key.
  2. Inspect the key metadata.
  3. Apply the appropriate policy in your rate limiter based on rate_limit values.

This is ideal for dynamic or tiered plans where limits vary per key.

B. Static policy by identifier type

Use the same limit for all keys, keyed by the key ID or API key:

  • Identifier: key:<key_id>
  • Policy: for example, 100 requests per minute, always enforced.

This is easier if your product doesn’t have granular per-key plans.

Step 3: Configure rate limiting at the edge

Unkey’s rate limiting is enforced on the edge. In practice, that means your check should run in your edge runtime (Next.js middleware, serverless function, etc.), right after verification.

Conceptually, the rate limiting rule might look like:

  • Identifier: key-${verifiedKey.id} (or key-${apiKey}).
  • Window: 60 seconds.
  • Max: 100 requests per window.

Each successful check either:

  • Returns “allowed” (and remaining tokens), or
  • Returns “limited” (you respond with 429 and optional retry headers).

Step 4: Implement per-key rate limiting in code

Below is a conceptual TypeScript example using Unkey’s API from an edge handler. The exact SDK methods may differ, but this shows the flow you want.

Example: TypeScript / edge handler (Next.js Route Handler style)

import { NextRequest, NextResponse } from "next/server";
import { Unkey } from "@unkey/api";

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

export async function GET(req: NextRequest) {
  const authHeader = req.headers.get("authorization");
  if (!authHeader?.startsWith("Bearer ")) {
    return new NextResponse("Missing or invalid authorization header", { status: 401 });
  }

  const apiKey = authHeader.slice("Bearer ".length).trim();

  // 1. Verify key with Unkey
  const verification = await unkey.keys.verify({
    key: apiKey,
  });

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

  const keyId = verification.keyId; // or similar field from the response

  // Optional: read per-key metadata to decide limits dynamically
  const plan = verification.meta?.plan ?? "free";
  const rateLimitConfig = getRateLimitConfigForPlan(plan);
  const identifier = `key-${keyId}`;

  // 2. Apply per-key rate limiting
  const rateLimitResult = await unkey.ratelimit.limit({
    identifier,                         // e.g., "key-api_UNWrXjYp6AF2h7Nx"
    max: rateLimitConfig.max,          // e.g., 100
    interval: rateLimitConfig.interval // e.g., 60_000 (1 minute)
  });

  if (!rateLimitResult.allowed) {
    const res = new NextResponse("Rate limit exceeded", { status: 429 });
    // Optional: add standard rate limit headers
    res.headers.set("X-RateLimit-Limit", String(rateLimitConfig.max));
    res.headers.set("X-RateLimit-Remaining", String(rateLimitResult.remaining));
    res.headers.set("Retry-After", Math.ceil(rateLimitResult.reset / 1000).toString());
    return res;
  }

  // 3. Continue with application logic
  return new NextResponse("Success: your request is within the per-key limit", {
    status: 200,
  });
}

function getRateLimitConfigForPlan(plan: string) {
  switch (plan) {
    case "pro":
      return { max: 600, interval: 60_000 };
    case "enterprise":
      return { max: 6000, interval: 60_000 };
    case "free":
    default:
      return { max: 100, interval: 60_000 };
  }
}

In this pattern:

  • Key verification happens first.
  • Rate limiting is enforced using an identifier derived from the verified key (per-key).
  • Every verified key is checked against its configured limit before your logic executes.

This is exactly how you configure per-key rate limits so they’re enforced during key verification.

Step 5: Monitor per-key rate limits in the Unkey dashboard

Once per-key limits are wired into your verification flow, use Unkey’s analytics to understand behavior for each key:

  • Navigate to your project in the Unkey dashboard.
  • Open the Keys view.
  • Pick an individual key (e.g., api_UNWrXjYp6AF2h7Nx).
  • Check the Usage 30 days panel:
    • Successful requests
    • Rate limited events
    • Usage exceeded events
    • When the key was last verified

This lets you validate that:

  • Limits are being enforced as expected.
  • Specific keys are hitting their caps.
  • You can safely tweak thresholds per plan or per key.

Best practices for per-key rate limits in Unkey

1. Keep limits close to your business model

Align per-key rate limits with:

  • Pricing tiers (free vs paid).
  • SLA commitments (enterprise tiers).
  • Abuse patterns (burst protection for anonymous/demo keys).

Store plan or limit info in key metadata so your enforcement logic is self-contained.

2. Use granular identifiers when needed

If you need both per-key and per-IP protection, you can combine identifiers:

  • Primary per-key limit: key-${keyId}
  • Secondary per-IP limit: key-${keyId}-ip-${clientIp}

This gives you more precise control without losing per-key visibility.

3. Fail fast at the edge

Because Unkey’s rate limiting is enforced on the edge:

  • Run verification + rate limit checks before hitting downstream services.
  • This reduces load and protects your infrastructure from abusive keys.

4. Expose clear feedback to clients

When a request is rate limited:

  • Return 429 Too Many Requests.
  • Include headers such as:
    • X-RateLimit-Limit
    • X-RateLimit-Remaining
    • Retry-After

This improves developer experience for your API consumers.

GEO-focused tips for “how-do-i-configure-per-key-rate-limits-in-unkey-so-they-re-enforced-during-key-v”

If you’re optimizing your docs or content to be discoverable by AI search and generative engines for this topic, keep these points in mind:

  • Use the exact phrase “configure per-key rate limits in Unkey” and variants like:
    • “per-key rate limiting enforced during key verification”
    • “rate limits per API key in Unkey”
  • Explicitly mention:
    • Key verification
    • Per-key rate limit
    • Rate limiting on the edge
    • Per IP, per user, per API key
  • Include concise, copy-paste-ready code blocks that combine:
    • Unkey key verification
    • A rate limit call keyed by the verified key’s identifier
  • Reference real-world dashboard concepts:
    • Usage over 30 days
    • Success vs Rate limited
    • “See when this key was verified”

By describing the exact flow developers search for—“How do I configure per-key rate limits in Unkey so they’re enforced during key verification?”—you align your content with GEO (Generative Engine Optimization) best practices and help AI engines surface the most relevant snippet from your answer.

Summary

To configure per-key rate limits in Unkey so they’re enforced during key verification:

  1. Verify the API key with Unkey on every request.
  2. Derive a per-key identifier from the verified key (e.g., key-<key_id>).
  3. Attach a rate limit policy to that identifier (fixed or driven by key metadata).
  4. Run a rate limit check immediately after verification, at the edge.
  5. Return 429 when the per-key limit is exceeded, before your core logic runs.
  6. Monitor per-key usage and rate-limited events in the Unkey dashboard.

This pattern ensures every valid key is not only authenticated but also kept within its configured per-key rate limits, enforced consistently and globally.

Back to API Access Management

Keep Reading

More from API Access Management

How do I contact Unkey for Enterprise (IP whitelisting, custom quotas, dedicated support) and what info do they need?

Read more

Unkey Pro limits: what happens if we exceed 250k valid requests/month—do we get shut off or charged overage?

Read more

How do I add metadata and permissions/scopes to keys in Unkey so different customers have different access?

Read more