Api Keys Vllnt

Bijection component for secure API key management — create, validate, revoke, rotate, and track usage

@bijectionhq/api-keys-vllntby bijectionhq

Markdown ▾

View Markdown Download MarkdownOpen in ChatGPT ↗Open in Claude ↗Open in Perplexity ↗

Bijection source

git clone https://github.com/bijectionhq/api-keys-vllnt.git
cd api-keys-vllnt
git checkout de026b054d4286092b16f7961271a301469990c3

Bijection repository access is required. Request access.

Description

Bijection component for secure API key management — create, validate, revoke, rotate, and track usage

Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.

Available as a reference

Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.

Getting started

Get the source at the revision above and read its package documentation.
Check the required Bijection SDK version, dependencies, and external service credentials.
Follow the package setup instructions and the guide to using components.
Exercise the component in your deployment according to your project’s verification rules.

Open source

Maintained source: bijectionhq/api-keys-vllnt. Based on vllnt/convex-api-keys. License: MIT. Consult the repository for license terms, notices, and contributor attribution.

From the upstream publisher

Convex component for secure API key management — create, validate, revoke, rotate, and track usage

Explore the demo ↗

Upstream overview

From the upstream package documentation.

@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 at VLLNT. Find the author on GitHub and X.

Use cases

From the upstream package documentation.

Developer products: let customers create and revoke keys for their integrations.
Internal tooling: provision credentials for CLI clients or scheduled jobs.
AI agent tools: issue a separate credential per authorized integration and enforce its permissions in your host.
Support and operations: pause a key or rotate it with a grace period while a client updates its configuration.

How it works

From the upstream package documentation.

Upstream package FAQ

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.

Use with agents and CLI

View Skill

Give your coding agent the component’s source identity and setup guidance.

agent-prompt.md

Help me integrate Api Keys Vllnt with Bijection.

Read: https://bijection.com/components/api-keys-vllnt/SKILL.md

Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.

Download SKILL.md llms.txt

Upstream README.md

View repository ↗

Documentation from vllnt/convex-api-keys, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

@vllnt/convex-api-keys

Secure API key management as a Convex component — create, validate, revoke, rotate, and track usage with built-in auth boundaries and structured audit logging.

const apiKeys = new ApiKeys(components.apiKeys, { prefix: "myapp" });
const { key, keyId } = await apiKeys.create(ctx, { name: "SDK Key", ownerId: orgId });
const result = await apiKeys.validate(ctx, { key: bearerToken });
// result.valid → { keyId, ownerId, scopes, ... } | result.reason

Features

Secure by default — SHA-256 hashed storage, constant-time comparison, prefix-indexed O(1) lookup, server-side secret generation.
Auth boundary — ownerId required on all admin mutations; prevents cross-tenant access.
Key types — secret and publishable keys with type-encoded prefixes.
Finite-use keys — remaining counter with atomic decrement for one-time-use tokens.
Disable / enable — reversible pause without revoking.
Rotation — configurable grace period (60s–30d) where both old and new keys are valid.
Bulk revoke by tag, tags & environments, multi-tenant scoping, usage tracking, input validation, structured audit logging.

Installation

Peer dependency: convex@^1.36.1

npm install convex@^1.36.1 @vllnt/convex-api-keys

import { defineApp } from "convex/server";
import apiKeys from "@vllnt/convex-api-keys/convex.config";

const app = defineApp();
app.use(apiKeys);
export default app;

Rate limiting is your responsibility — add @convex-dev/rate-limiter at your HTTP action/mutation layer where you have real caller context (IP, auth, plan tier). The component has none.

Usage

import { ApiKeys } from "@vllnt/convex-api-keys";
import { components } from "./_generated/api";

const apiKeys = new ApiKeys(components.apiKeys, {
  prefix: "myapp",       // key prefix (default: "vk")
  defaultType: "secret",
});

// Create — secret material is generated server-side, returned once.
const { key, keyId } = await apiKeys.create(ctx, {
  name: "Production SDK Key",
  ownerId: orgId,
  type: "secret",
  scopes: ["read:users", "write:orders"],
  tags: ["sdk", "v2"],
  env: "live",
});
// key = "myapp_secret_live_a1b2c3d4_<64-char-hex>"

// Validate — track usage and narrow on `valid`.
const result = await apiKeys.validate(ctx, { key: bearerToken });
if (!result.valid) {
  // result.reason: "malformed" | "not_found" | "revoked" | "expired" | "exhausted" | "disabled"
  return new Response("Unauthorized", { status: 401 });
}
const { ownerId, scopes, tags, env, type, metadata, remaining } = result;

See docs/API.md for the full method reference, key format, and lifecycle.

API Reference

Method	Ctx	Description
`create(ctx, options)`	mutation	Create a new API key
`validate(ctx, { key })`	mutation	Validate and track usage
`revoke(ctx, { keyId, ownerId })`	mutation	Permanently revoke a key
`revokeByTag(ctx, { ownerId, tag })`	mutation	Bulk revoke by tag
`rotate(ctx, { keyId, ownerId, gracePeriodMs? })`	mutation	Rotate with grace period
`update(ctx, { keyId, ownerId, name?, ... })`	mutation	Update metadata in-place
`disable(ctx, { keyId, ownerId })`	mutation	Temporarily disable
`enable(ctx, { keyId, ownerId })`	mutation	Re-enable a disabled key
`configure(ctx, { ... })`	mutation	Runtime config (admin-only)
`list(ctx, { ownerId, env?, status?, limit? })`	query	List keys (paginated, default 100)
`listByTag(ctx, { ownerId, tag, limit? })`	query	Filter by tag
`getUsage(ctx, { keyId, ownerId })`	query	Usage counter (O(1))

Full reference: docs/API.md.

Security

Protects against accidental cross-tenant bugs in honest host apps — the ownerId check does NOT defend against a compromised host passing a forged ownerId.
Derive ownerId from your own auth layer (e.g. ctx.auth.getUserIdentity()) before passing it in.
Raw keys are never stored — only the SHA-256 hash; the raw value is returned once at creation.

See docs/API.md.

Testing

import { convexTest } from "convex-test";
import { register } from "@vllnt/convex-api-keys/test";
import shardedCounterTest from "@convex-dev/sharded-counter/test";

const t = convexTest(schema, modules);
register(t, "apiKeys");
shardedCounterTest.register(t, "apiKeys/shardedCounter");