Roles and permissions

Role-based access control with resource-level scoping. Owner / admin / member by default; customizable per project.

vly’s built-in auth includes a role-based access control (RBAC) system. Every project starts with three roles — owner, admin, member — and you can add more or rename them.

The default roles

Role	What they can do
Owner	Everything. Manage billing. Cannot be removed (must transfer first).
Admin	Manage members, edit any data, configure integrations. Cannot manage billing.
Member	Use the app, edit data they created (or shared resources, depending on app).

The exact permissions depend on your app — vly generates the role check pattern but you decide who can do what.

Adding a role

Add a "viewer" role. Viewers can read everything in their workspace but
cannot create, edit, or delete anything.

vly:

1. Adds viewer to the role enum in the schema.
2. Updates every mutation to refuse if the caller is a viewer.
3. Adds the new role option in the workspace member UI.

Resource-level scoping

Beyond role-level permissions, scope by who owns a resource:

Members can edit and delete only the tasks they created.
Admins can edit and delete any task in the workspace.

The pattern in code:

convex/tasks.ts

export const deleteTask = mutation({
  args: { id: v.id("tasks") },
  handler: async (ctx, { id }) => {
    const identity = await ctx.auth.getUserIdentity();
    const task = await ctx.db.get(id);
    if (!task) throw new Error("Not found");

    const membership = await ctx.db
      .query("memberships")
      .withIndex("by_workspace_and_user", q =>
        q.eq("workspaceId", task.workspaceId).eq("userId", identity.subject))
      .unique();

    const isAdmin = ["owner", "admin"].includes(membership?.role);
    const isCreator = task.createdBy === identity.subject;

    if (!isAdmin && !isCreator) {
      throw new Error("Permission denied");
    }

    await ctx.db.delete(id);
  },
});

vly generates this pattern when you describe role-aware behavior in a prompt.

Common patterns

Owner-only billing

“Only owners can change the workspace plan or update billing details.”

Admin-only invites

“Admins and owners can invite new members. Members cannot.”

Self-service for members

“Members can edit their own profile, but not other members’.”

Public read, restricted write

“Anyone signed in can read all resources; only the creator can edit.”

Tips

Define roles in plain English in the prompt. “Members can do X but not Y” is clearer than trying to enumerate every permission.

Test by signing in as different roles. Don’t trust that the agent generated the right checks — sign in as a member and try to do admin-only actions.

Related

Built-in auth

The auth system.

Workspace roles

Workspace-level role management.

Auth flows

Architectural patterns.