Create, validate, and manage API keys in Convex with secure hashing, multi-tenant isolation, usage tracking, and rotation capabilities.
npm install @vllnt/convex-api-keysAPI Keys is secure API key management as a Convex component: create, validate, rotate, revoke, disable, and track usage for SHA-256 hashed keys, with constant-time comparison and O(1) prefix-indexed lookup. Every admin mutation is gated by an `ownerId` auth boundary for multi-tenant isolation, secret material is generated server-side and returned once, and rotation supports a configurable grace period where old and new keys both validate. Keys, usage, and audit logs live in the component's own sandboxed tables, and it runs identically on Convex Cloud and self-hosted convex-backend.
@vllnt/convex-api-keys provides a complete API key system for Convex apps. You can create keys with scopes and metadata, validate them in HTTP actions with constant-time comparison, and track usage automatically. The component handles secure storage with SHA-256 hashing and prevents cross-tenant access.
The rotate() method creates a new key while keeping the old one valid for a configurable grace period (60 seconds to 30 days). Both keys work during the transition, allowing you to update clients gradually without service interruption.
Every operation requires an ownerId parameter that scopes all queries and mutations to a specific tenant. This prevents accidental cross-tenant access and enables safe multi-tenant API key management with proper isolation boundaries.
Keys support a remaining counter that decrements atomically on each validation. When it reaches zero, the key becomes exhausted and invalid. Usage tracking is powered by @convex-dev/sharded-counter for high-throughput scenarios.
@vllnt/convex-api-keys requires an ownerId parameter on all admin operations like create, revoke, and update. Every query is scoped by this ownerId, preventing bugs from accidentally operating on another tenant's keys. However, you must derive the ownerId from your own auth system to ensure security.
@vllnt/convex-api-keys handles key validation and usage tracking but does not provide rate limiting. You should add @convex-dev/rate-limiter at your HTTP action layer where you have caller context like IP addresses and user plans to make informed rate limiting decisions.
@vllnt/convex-api-keys supports secret and publishable key types with encoded prefixes. You can also create finite-use keys with a remaining counter, set expiration dates, add scopes for permissions, and organize keys with tags and environment labels.
@vllnt/convex-api-keys uses SHA-256 hashing for key storage, constant-time comparison for validation, and server-side secret generation. Keys are never transmitted from the client, and lookups use prefix indexing for O(1) performance while maintaining security.