API Tokens

Copy codenpm install convex-api-tokens

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import apiTokens from "convex-api-tokens/convex.config";

const app = defineApp();
app.use(apiTokens);

export default app;

Copy code// convex/tokens.ts
import { ApiTokens } from "convex-api-tokens";
import { components } from "./_generated/api.js";

const apiTokens = new ApiTokens(components.apiTokens);

Copy codeconst apiTokens = new ApiTokens(components.apiTokens, {
  API_TOKENS_ENCRYPTION_KEY: process.env.API_TOKENS_ENCRYPTION_KEY,
});

Copy codeimport { mutation } from "./_generated/server.js";
import { v } from "convex/values";

export const createToken = mutation({
  args: { name: v.optional(v.string()) },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);

    const result = await apiTokens.create(ctx, {
      namespace: userId,
      name: args.name ?? "My API Key",
      metadata: { scopes: ["read", "write"] },
      expiresAt: Date.now() + 90 * 24 * 60 * 60 * 1000, // 90 days
      maxIdleMs: 30 * 24 * 60 * 60 * 1000, // 30 day idle timeout
    });

    // result.token is the raw key — show it once to the user
    // result.tokenPrefix is "sk_ab12...ef56" for display
    return result;
  },
});

Copy codeexport const validateToken = mutation({
  args: { token: v.string() },
  handler: async (ctx, args) => {
    const result = await apiTokens.validate(ctx, { token: args.token });

    if (!result.ok) {
      throw new Error(`Token invalid: ${result.reason}`);
      // reason: "expired" | "idle_timeout" | "revoked" | "invalid"
    }

    return { namespace: result.namespace, metadata: result.metadata };
  },
});

Copy codeexport const rotateToken = mutation({
  args: { token: v.string() },
  handler: async (ctx, args) => {
    const result = await apiTokens.refresh(ctx, { token: args.token });

    if (!result.ok) throw new Error(result.reason);
    return result; // { token, tokenPrefix, tokenId }
  },
});

Copy code// Single token by raw value
await apiTokens.invalidate(ctx, { token: rawToken });

// Single token by ID (admin dashboard)
await apiTokens.invalidateById(ctx, { tokenId: "token_id_here" });

// All tokens for a user
await apiTokens.invalidateAll(ctx, { namespace: userId });

// All tokens created before a date
await apiTokens.invalidateAll(ctx, {
  namespace: userId,
  before: Date.now() - 90 * 24 * 60 * 60 * 1000,
});

Copy codeexport const listTokens = query({
  args: {},
  handler: async (ctx) => {
    const userId = await getAuthUserId(ctx);
    return await apiTokens.list(ctx, {
      namespace: userId,
      includeRevoked: false,
    });
  },
});

Copy codeimport { withTokenAuth } from "convex-api-tokens";
import { v } from "convex/values";

export const protectedMutation = mutation({
  args: { token: v.string(), data: v.string() },
  handler: withTokenAuth(apiTokens, async (ctx, args, auth) => {
    // auth = { namespace, metadata, tokenId }
    // Throws "Unauthorized: <reason>" if token is invalid
    return { saved: true, user: auth.namespace };
  }),
});

Copy code// In a cron job (convex/crons.ts)
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api.js";

const crons = cronJobs();
crons.daily("cleanup tokens", { hourUTC: 3, minuteUTC: 0 }, internal.tokens.cleanupExpired);
export default crons;

// In your tokens file
export const cleanupExpired = internalMutation({
  handler: async (ctx) => {
    const deleted = await apiTokens.cleanup(ctx, {
      olderThanMs: 30 * 24 * 60 * 60 * 1000, // 30 days
    });
    console.log(`Cleaned up ${deleted} expired tokens`);
  },
});

Copy codeconst apiTokens = new ApiTokens(components.apiTokens, {
  onInvalidate: async (info) => {
    console.log(`Token ${info.method}: namespace=${info.namespace}`);
    // info.method: "invalidate" | "invalidateById" | "invalidateAll"
    // info.tokenId: set for invalidateById
    // info.count: set for invalidateAll
    // info.namespace: set when available
  },
});

Copy code// Define your metadata type
type TokenMeta = {
  scopes: ("read" | "write" | "admin")[];
  orgId: string;
};

// Pass it as a generic
const apiTokens = new ApiTokens<TokenMeta>(components.apiTokens);

// Now metadata is typed everywhere
const result = await apiTokens.validate(ctx, { token });
if (result.ok) {
  result.metadata?.scopes; // ("read" | "write" | "admin")[]
  result.metadata?.orgId;  // string
}

const tokens = await apiTokens.list(ctx, { namespace: userId });
tokens[0].metadata?.scopes; // typed!

Copy code// Initialize with encryption key (reads from process.env in app context)
const apiTokens = new ApiTokens(components.apiTokens, {
  API_TOKENS_ENCRYPTION_KEY: process.env.API_TOKENS_ENCRYPTION_KEY,
});

// Store a key — encrypted automatically server-side
export const storeApiKey = mutation({
  args: { keyName: v.string(), value: v.string() },
  handler: async (ctx, args) => {
    await apiTokens.storeKey(ctx, {
      namespace: "my_app",
      keyName: args.keyName,
      value: args.value,
    });
  },
});

// Retrieve a key — decrypted automatically server-side
export const getApiKey = query({
  args: { keyName: v.string() },
  handler: async (ctx, args) => {
    return await apiTokens.getKey(ctx, {
      namespace: "my_app",
      keyName: args.keyName,
    });
  },
});

Copy codeimport { createTokenAuth } from "convex-api-tokens";

const withApiToken = createTokenAuth(components.apiTokens);

export const myEndpoint = httpAction(async (ctx, request) => {
  const auth = await withApiToken(ctx, request);
  if (!auth.ok) {
    return new Response(JSON.stringify({ error: auth.reason }), {
      status: 401,
      headers: { "Content-Type": "application/json" },
    });
  }
  // auth.namespace and auth.metadata available here
  return new Response(JSON.stringify({ user: auth.namespace }));
});

Copy code// Convex user ID (already a string)
await apiTokens.create(ctx, { namespace: userId, ... });

// Numeric ID — convert to string
await apiTokens.create(ctx, { namespace: String(orgId), ... });