Auth integration

How Convex’s auth context works inside queries, mutations, and actions.

Every Convex function has access to the calling user via ctx.auth.getUserIdentity(). Use it to scope reads and writes to the current user.

In a query

export const myStuff = query({
  args: {},
  handler: async (ctx) => {
    const user = await ctx.auth.getUserIdentity();
    if (!user) throw new Error("Not signed in");

    return await ctx.db
      .query("things")
      .withIndex("by_owner", q => q.eq("ownerId", user.subject as Id<"users">))
      .collect();
  },
});

In a mutation

Same shape — get the identity, throw on missing, write scoped to the user.

In an action

Identical.

What’s in the identity

{
  subject:  string,           // user ID (matches ctx.db.get(Id<"users">))
  email:    string | undefined,
  name:     string | undefined,
  pictureUrl: string | undefined,
  // additional provider-specific fields
}

Common patterns

Require sign-in

const user = await ctx.auth.getUserIdentity();
if (!user) throw new Error("Not signed in");

Optional sign-in

const user = await ctx.auth.getUserIdentity();
return await ctx.db
  .query("posts")
  .withIndex("by_visibility",
    q => q.eq("visibility", user ? "members" : "public"))
  .collect();

Role check

const user       = await ctx.auth.getUserIdentity();
const membership = await ctx.db
  .query("memberships")
  .withIndex("by_user_and_workspace",
    q => q.eq("userId", user.subject).eq("workspaceId", workspaceId))
  .unique();
if (membership?.role !== "admin") throw new Error("Permission denied");

Related

Built-in auth

The auth system overview.

Roles & permissions

Role-based access patterns.

Data access control

Security best practices.