convex-deploy-auth

Small helpers for server-to-Convex writes. This is not a Convex component and does not own tables.

Convex component functions have no ctx.auth. If a Node process (or any non-Convex caller) invokes mutations over HTTP, you need your own gate. This package is that gate: a shared secret stored as a Convex deployment env var, passed as deploySecret on write args.

Apps that only call components from other Convex functions should not use this. Put auth in those app wrappers instead (ctx.auth, API keys, etc.).

Install

npm install convex-deploy-auth

On the Convex deployment:

CONVEX_DEPLOY_SECRET=a-long-random-string

In a mutation:

import { assertDeploySecret, deploySecretArg } from "convex-deploy-auth";

export const save = mutation({
  args: { data: v.any(), ...deploySecretArg },
  handler: async (ctx, args) => {
    assertDeploySecret(args.deploySecret);
    // ...
  },
});

If CONVEX_DEPLOY_SECRET is unset, assertDeploySecret is a no-op so local dev works without extra config.

tenantIdArg / resolveTenantId are optional multi-tenant string helpers (tenantId defaults to "default").