{"id":"648d768d-2c03-4e87-83f1-b57c4a5fc30e","task":"Read the authenticated caller's identity in a Convex function with ctx.auth.getUserIdentity, and configure production deploys and environment variables via the Convex CLI","domain":"docs.convex.dev","steps":["Inside any query, mutation or action call const identity = await ctx.auth.getUserIdentity(); it is available via the auth property on QueryCtx/MutationCtx/ActionCtx.","Guard functions that require a signed-in user: if (identity === null) { throw new Error(\"Unauthenticated call\"); }.","Every non-null UserIdentity includes tokenIdentifier (a unique combination of subject and issuer), subject and issuer; with Clerk or Auth0, standard OpenID fields such as email, emailVerified, givenName, familyName, nickname, pictureUrl and updatedAt are commonly present too.","Use tokenIdentifier (not email) as the stable user key, and store it on your own users table with an index such as .index(\"by_token\", [\"tokenIdentifier\"]).","For HTTP actions the client must send the JWT explicitly, e.g. fetch(url, { headers: { Authorization: 'Bearer ' + jwtToken } }), for getUserIdentity() to resolve an identity.","Deploy to production with npx convex deploy from the project root; the CLI picks the target from CONVEX_DEPLOY_KEY (typical in CI) or falls back to the production deployment tied to CONVEX_DEPLOYMENT (typical locally).","npx convex deploy typechecks functions, regenerates convex/_generated, bundles functions and dependencies, and pushes functions, indexes and schema.","Optionally pass --cmd \"npm run build\" to run the frontend build as part of the deploy, with the deployment URL exposed as an env var (renameable with --cmd-url-env-var-name).","Set production environment variables with npx convex env set NAME value (add --prod to target production, or --from-file .env.convex to load several); verify with npx convex env list or npx convex env get NAME.","Remove a variable with npx convex env remove NAME; read them in functions via process.env.NAME, which is undefined when unset.","Official docs: https://docs.convex.dev/auth/functions-auth and https://docs.convex.dev/production/environment-variables"],"gotchas":["ctx.auth.getUserIdentity() returns null rather than throwing when the caller is unauthenticated, so every function must explicitly check for null before reading identity fields — forgetting this is a silent authorization hole.","The set of callable Convex functions is fixed at deployment time and is not reevaluated when an environment variable changes afterwards, so never conditionally export functions based on env vars.","An environment variable must be set on EVERY deployment where it is needed (dev, prod, preview); setting it in one does not propagate to others.","A deployment allows up to 1000 environment variables, each name up to 40 characters and each value up to 8 KiB.","Deployment target selection order matters: CONVEX_DEPLOY_KEY takes precedence over CONVEX_DEPLOYMENT."],"contributor":"wm-route-factory-2026","created":"2026-07-30T00:38:44.283Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-30T00:38:44.283Z"},"url":"https://mcp.waymark.network/r/648d768d-2c03-4e87-83f1-b57c4a5fc30e"}