Use Cases

Use UsefulKey to validate incoming requests with an API key before your handler runs.

Works with: uk.verifyKey({ key, ... })
Optional: include caller context (ip, custom identifier) for analytics and rate limits
If you enable rate limiting, pass a namespace to segment counters

Attach scopes to keys and require them at verification time. A request is authorized only if the key contains all requested scopes.

Works with: Permissions / Scopes plugin
Manage scopes: uk.grantScopes, uk.revokeScopes, uk.setScopes, uk.getScopes
Enforce by passing scopes to uk.verifyKey({ key, scopes: ["..."] })

Apply fixed-window or token-bucket rate limits per identifier and namespace. Limits can be set per call or via a default.

Works with: Rate limit plugin
Per call: provide rateLimit, identifier, and namespace to uk.verifyKey
Default limits: configure a plugin default to apply when per-call limits are omitted

Related docs: Rate limit

Track a remaining-uses counter stored on each key. On successful verification, decrement; when it reaches 0, block further use.

Works with: Usage limits per key plugin
Create with a budget: uk.createKey({ usesRemaining: 100 })
Manage at runtime: uk.setUsesRemaining, uk.topUpUses, uk.getUsesRemaining, uk.clearUsageLimit

Manage the full lifecycle of API keys with built-in helpers.

Create: uk.createKey({ userId?, metadata?, expiresAt?, usesRemaining? })
Rotate: create a new key, migrate clients, then revoke the old key
Revoke: uk.revokeKey(id) to immediately block
Expire: set expiresAt on creation, or extend with uk.extendKeyExpiry(id, ms)
Cleanup: uk.sweepExpired({ strategy: "soft_then_hard" | "hard" })

Related docs: API reference

Add coarse or network-level controls to quickly allow or block access.

Temporarily disable a key via metadata: Enable / Disable plugin
- uk.disableKey(id), uk.enableKey(id)
Restrict by source IP: IP Access Control (Static) or IP Access Control (Memory)
- Pass ip to uk.verifyKey({ key, ip })

Combine these with scopes, quotas, and rate limits to build layered defenses and clear product tiers.