When writing Convex handlers, use the `getAuthUserId` function to get the logged in user's ID. You can then pass this to `ctx.db.get` in queries or mutations to get the user's data.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
When writing Convex handlers, use the getAuthUserId function to get the logged in user's ID. You can then pass this to ctx.db.get in queries or mutations to get the user's data.
IMPORTANT: You can only use this within the convex/ directory.
// convex/users.ts
import { getAuthUserId } from "@convex-dev/auth/server";
import { query } from "./_generated/server";
export const currentLoggedInUser = query({
args: {},
returns: v.union(v.null(), v.object({
_id: v.id("users"),
name: v.optional(v.string()),
email: v.optional(v.string()),
image: v.optional(v.string()),
})),
handler: async (ctx) => {
const userId = await getAuthUserId(ctx);
if (!userId) {
return null;
}
const user = await ctx.db.get(userId);
if (!user) {
return null;
}
console.log("User", user.name, user.image, user.email);
return user;
}
});
If you want to get the current logged in user's data on the frontend, use this function defined in convex/auth.ts:
// convex/auth.ts
import { getAuthUserId } from "@convex-dev/auth/server";
import { query } from "./_generated/server";
export const loggedInUser = query({
args: {},
handler: async (ctx) => {
const userId = await getAuthUserId(ctx);
if (!userId) {
return null;
}
const user = await ctx.db.get(userId);
if (!user) {
return null;
}
return user;
},
});
Then use the loggedInUser query in your React component:
// src/App.tsx
import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";
function App() {
const user = useQuery(api.auth.loggedInUser);
if (user === undefined) {
return <div>Loading...</div>;
}
if (user === null) {
return <div>Not logged in</div>;
}
return <div>Welcome, {user.name}!</div>;
}
The "users" table within authTables has this schema:
const users = defineTable({
name: v.optional(v.string()),
image: v.optional(v.string()),
email: v.optional(v.string()),
emailVerificationTime: v.optional(v.number()),
phone: v.optional(v.string()),
phoneVerificationTime: v.optional(v.number()),
isAnonymous: v.optional(v.boolean()),
})
.index("email", ["email"])
.index("phone", ["phone"]);
When defining your schema with authentication, always spread authTables:
// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
import { authTables } from "@convex-dev/auth/server";
const applicationTables = {
// Your application tables here
posts: defineTable({
authorId: v.id("users"),
title: v.string(),
content: v.string(),
}).index("by_author", ["authorId"]),
};
export default defineSchema({
...authTables,
...applicationTables,
});
Create a helper function to get the logged-in user and throw if not authenticated:
// convex/utils.ts
import { getAuthUserId } from "@convex-dev/auth/server";
import { QueryCtx, MutationCtx } from "./_generated/server";
import { Doc } from "./_generated/dataModel";
export async function getLoggedInUser(ctx: QueryCtx | MutationCtx): Promise<Doc<"users">> {
const userId = await getAuthUserId(ctx);
if (!userId) {
throw new Error("Not authenticated");
}
const user = await ctx.db.get(userId);
if (!user) {
throw new Error("User not found");
}
return user;
}
export async function getLoggedInUserOrNull(ctx: QueryCtx | MutationCtx): Promise<Doc<"users"> | null> {
const userId = await getAuthUserId(ctx);
if (!userId) {
return null;
}
return await ctx.db.get(userId);
}
// convex/posts.ts
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { getLoggedInUser } from "./utils";
export const createPost = mutation({
args: {
title: v.string(),
content: v.string(),
},
returns: v.id("posts"),
handler: async (ctx, args) => {
const user = await getLoggedInUser(ctx);
return await ctx.db.insert("posts", {
authorId: user._id,
title: args.title,
content: args.content,
});
},
});
export const myPosts = query({
args: {},
handler: async (ctx) => {
const user = await getLoggedInUser(ctx);
return await ctx.db
.query("posts")
.withIndex("by_author", (q) => q.eq("authorId", user._id))
.collect();
},
});
CRITICAL: Auth state does NOT propagate to scheduled jobs. getAuthUserId() and ctx.getUserIdentity() will ALWAYS return null from within a scheduled job.
// convex/tasks.ts
import { mutation, internalMutation } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";
import { getAuthUserId } from "@convex-dev/auth/server";
export const scheduleTask = mutation({
args: { taskData: v.string() },
returns: v.null(),
handler: async (ctx, args) => {
const userId = await getAuthUserId(ctx);
if (!userId) {
throw new Error("Not authenticated");
}
// Pass the userId to the scheduled function
await ctx.scheduler.runAfter(0, internal.tasks.processTask, {
userId,
taskData: args.taskData,
});
return null;
},
});
export const processTask = internalMutation({
args: {
userId: v.id("users"),
taskData: v.string(),
},
returns: v.null(),
handler: async (ctx, args) => {
// Use the passed userId instead of getAuthUserId
const user = await ctx.db.get(args.userId);
if (!user) {
throw new Error("User not found");
}
// Process the task with user context
console.log(`Processing task for user: ${user.name}`);
return null;
},
});
The auth handler should be in convex/http.ts:
// convex/http.ts
import { httpRouter } from "convex/server";
import { auth } from "./auth";
const http = httpRouter();
auth.addHttpRoutes(http);
export default http;
Define new HTTP endpoints in a separate file to avoid modifying the auth handler:
// convex/router.ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
const router = httpRouter();
router.route({
path: "/api/webhook",
method: "POST",
handler: httpAction(async (ctx, req) => {
// Handle webhook
const body = await req.json();
return new Response(JSON.stringify({ received: true }), {
status: 200,
headers: { "Content-Type": "application/json" },
});
}),
});
export default router;
Always make sure your UIs work well with anonymous users:
// src/components/UserProfile.tsx
import { useQuery } from "convex/react";
import { api } from "../../convex/_generated/api";
export function UserProfile() {
const user = useQuery(api.auth.loggedInUser);
// Loading state
if (user === undefined) {
return <div className="animate-pulse">Loading...</div>;
}
// Anonymous / not logged in
if (user === null) {
return (
<div>
<p>Welcome, Guest!</p>
<button>Sign In</button>
</div>
);
}
// Logged in user
return (
<div>
{user.image && <img src={user.image} alt={user.name || "User"} />}
<p>Welcome, {user.name || user.email || "User"}!</p>
</div>
);
}
If you need to add more fields to the users table, you can extend it in your schema:
// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
import { authTables } from "@convex-dev/auth/server";
// Extend the users table with additional fields
const extendedAuthTables = {
...authTables,
users: defineTable({
// Original auth fields
name: v.optional(v.string()),
image: v.optional(v.string()),
email: v.optional(v.string()),
emailVerificationTime: v.optional(v.number()),
phone: v.optional(v.string()),
phoneVerificationTime: v.optional(v.number()),
isAnonymous: v.optional(v.boolean()),
// Your custom fields
role: v.optional(v.union(v.literal("admin"), v.literal("user"))),
bio: v.optional(v.string()),
preferences: v.optional(v.object({
theme: v.union(v.literal("light"), v.literal("dark")),
notifications: v.boolean(),
})),
})
.index("email", ["email"])
.index("phone", ["phone"])
.index("by_role", ["role"]),
};
export default defineSchema({
...extendedAuthTables,
// Your other tables
});
export const sensitiveQuery = query({
args: {},
handler: async (ctx) => {
const userId = await getAuthUserId(ctx);
if (!userId) {
throw new Error("Authentication required");
}
// Continue with authenticated logic
},
});
// Public mutation that checks auth
export const deleteAccount = mutation({
args: {},
returns: v.null(),
handler: async (ctx) => {
const userId = await getAuthUserId(ctx);
if (!userId) {
throw new Error("Not authenticated");
}
// Call internal function for the actual deletion
await ctx.runMutation(internal.users.deleteUserData, { userId });
return null;
},
});
// Internal mutation that doesn't check auth (already verified)
export const deleteUserData = internalMutation({
args: { userId: v.id("users") },
returns: v.null(),
handler: async (ctx, args) => {
// Delete user's data
const posts = await ctx.db
.query("posts")
.withIndex("by_author", (q) => q.eq("authorId", args.userId))
.collect();
for (const post of posts) {
await ctx.db.delete(post._id);
}
return null;
},
});
function ProtectedComponent() {
const user = useQuery(api.auth.loggedInUser);
// IMPORTANT: Check for undefined (loading) before null (not authenticated)
if (user === undefined) {
return <LoadingSpinner />;
}
if (user === null) {
return <Navigate to="/login" />;
}
return <Dashboard user={user} />;
}