API Keys

Create, validate, and manage API keys in Convex with secure hashing, multi-tenant isolation, usage tracking, and rotation capabilities.

Installation

npm install @vllnt/convex-api-keys

About API Keys

@vllnt/convex-api-keys manages the lifecycle of credentials your application issues to API consumers. Store hashed keys, associate them with a trusted owner, and validate usage through your backend.

Create keys, validate them, list owner-specific metadata, and read usage counts. Disable and enable offer a reversible pause; revoke ends access. Rotation allows a configured overlap period. Tags, environments, and finite-use counters support host-defined credential policies.

The host authenticates administrators, derives ownerId from trusted identity, and enforces endpoint permissions. An ownerId comparison is not proof of identity by itself. Keep secret keys out of logs and client bundles; publishable keys are identifiers, not authorization secrets.

Maintained by [bntvllnt](https://bntvllnt.com) at [VLLNT](https://vllnt.com). Find the author on [GitHub](https://github.com/bntvllnt) and [X](https://x.com/bntvllnt).

Benefits

Use cases

how to implement API key authentication in Convex

@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.

Convex API key rotation with zero downtime

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.

multi tenant API key management Convex

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.

track API key usage limits in Convex

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.

Frequently asked questions

How does @vllnt/convex-api-keys prevent cross-tenant access?

@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.

Can I use this component for rate limiting API requests?

@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.

What key types does the component support?

@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.

How secure is the key storage in this component?

@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.

Links

Convex
Components

Open-source building blocks for your Convex app

Browse components in this category.

All All

Loading components