# Built-in Roles in Kaneo: Viewer, Member, Admin, and Owner Permissions Explained

> Understand Kaneo's built-in roles Viewer Member Admin and Owner Explore their distinct permissions from read-only access to full workspace control and deletion capabilities.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: deep-dive
- Published: 2026-08-29

---

**Kaneo defines four built-in workspace roles—Viewer, Member, Admin, and Owner—in [`packages/permissions/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/permissions/src/index.ts), with permissions ranging from read-only project access to full workspace management and deletion capabilities.**

Kaneo implements a hierarchical role-based access control (RBAC) system using four distinct permission levels. These roles extend the base organization statements from better-auth and are instantiated using the `createAccessControl` factory to govern access across projects, tasks, labels, and workspace settings.

## The Four Built-in Kaneo Roles and Their Capabilities

Kaneo’s permission model is defined in [`packages/permissions/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/permissions/src/index.ts), where each role is created using `ac.newRole` method calls at specific line numbers. The following sections detail the granular permissions assigned to each built-in role.

### Viewer (Line 19)

The **Viewer** role provides minimal read-only access suitable for stakeholders who need visibility without modification rights.

- **Projects**: `read`
- **Tasks**: `read`
- **Labels**: `read`
- **Workspace**: `read`

Defined at line 19 via `ac.newRole`, this role cannot create, update, or delete any resources within the workspace.

### Member (Line 27)

The **Member** role serves as the standard contributor level, enabling active participation in project work while restricting destructive actions and administrative settings.

- **Projects**: `create`, `read`
- **Tasks**: `create`, `read`, `update`
- **Labels**: `create`, `read`, `update`, `delete`
- **Workspace**: `read`

As implemented in [`packages/permissions/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/permissions/src/index.ts) at line 27, **Member** can create and modify most objects but cannot delete projects or manage workspace-level configurations.

### Admin (Line 35)

The **Admin** role grants comprehensive management capabilities over content and users while restricting the most destructive workspace actions.

- **Projects**: `create`, `read`, `update`, `delete`, `share`
- **Tasks**: `create`, `read`, `update`, `delete`, `assign`
- **Labels**: `create`, `read`, `update`, `delete`
- **Workspace**: `read`, `update`, `manage_settings`

Defined at line 35, **Admin** has full control over projects, tasks, and labels, including the ability to assign tasks to users and share projects. Admins can modify workspace settings but cannot delete the workspace itself.

### Owner (Line 43)

The **Owner** role possesses unrestricted access, including the unique ability to delete the entire workspace.

- **Projects**: `create`, `read`, `update`, `delete`, `share`
- **Tasks**: `create`, `read`, `update`, `delete`, `assign`
- **Labels**: `create`, `read`, `update`, `delete`
- **Workspace**: `read`, `update`, `delete`, `manage_settings`

This role is instantiated at line 43 with identical permissions to **Admin** plus the critical `delete` action on the workspace resource, making it the only role capable of permanent workspace removal.

## How Roles Are Defined in the Source Code

According to the Kaneo source code, all built-in roles share base statements imported from `better-auth/plugins/organization/access` (lines 3-7 of [`packages/permissions/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/permissions/src/index.ts)). The system uses the `createAccessControl(statement)` factory to generate the access control object, then extends these base permissions through sequential `ac.newRole` calls.

Each role definition aggregates specific actions across four resource types: `project`, `task`, `label`, and `workspace`. The `builtInRoles` object exports these definitions for consumption throughout the application.

## Checking Role Permissions Programmatically

The `@kaneo/permissions` package provides utilities to verify capabilities at runtime and enforce authorization in API handlers.

### Verify Specific Capabilities

Use the `can` method on any built-in role to check specific permissions:

```typescript
import { builtInRoles } from "@kaneo/permissions";

// Check if a member can delete a task
const canDeleteTask = builtInRoles.member.can("task", "delete"); // returns false

// Check if an admin can assign a task
const canAssignTask = builtInRoles.admin.can("task", "assign"); // returns true

```

### Enforce Permissions in API Middleware

The `requireWorkspacePermission` middleware integrates with Kaneo’s routing system to protect endpoints:

```typescript
import { requireWorkspacePermission } from "@kaneo/permissions";

export const deleteProject = createRoute({
  method: "delete",
  path: "/projects/:id",
  middleware: [requireWorkspacePermission("project", "delete")],
})(async (c) => {
  // Handler logic executes only for Admin or Owner roles
});

```

This middleware rejects requests from **Viewer** and **Member** roles, allowing only **Admin** and **Owner** to execute project deletions.

### Audit All Role Capabilities

To programmatically inspect the permission matrix:

```typescript
import { builtInRoles } from "@kaneo/permissions";

for (const [name, role] of Object.entries(builtInRoles)) {
  console.log(`${name} can:`)
  for (const [resource, actions] of Object.entries(role.statements)) {
    console.log(`  ${resource}: ${actions.join(", ")}`);
  }
}

```

## Summary

- **Viewer**: Read-only access defined at line 19; cannot modify any resources.
- **Member**: Content creation and editing rights defined at line 27; cannot delete projects or manage workspace settings.
- **Admin**: Full content management including task assignment and project sharing defined at line 35; can modify workspace settings but not delete the workspace.
- **Owner**: Unrestricted access defined at line 43; the only role capable of deleting the workspace.

The permission system is tested in [`packages/permissions/src/index.test.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/permissions/src/index.test.ts) and validated through integration tests in [`tests/api-integration/workspace-rbac.test.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api-integration/workspace-rbac.test.ts).

## Frequently Asked Questions

### What is the difference between Admin and Owner roles in Kaneo?

The **Owner** role includes the `delete` action on the workspace resource, while the **Admin** role does not. Both roles share identical permissions for projects, tasks, and labels—including sharing projects and assigning tasks—but only **Owner** can permanently delete the workspace itself.

### Can I create custom roles beyond the four built-in roles?

The current implementation in [`packages/permissions/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/permissions/src/index.ts) exports a fixed `builtInRoles` object containing only Viewer, Member, Admin, and Owner. While the underlying `createAccessControl` system supports additional roles via `ac.newRole`, extending beyond these four would require modifying the permissions package source code.

### How do I check if a user has permission to perform a specific action?

Import `builtInRoles` from `@kaneo/permissions` and use the `can(resource, action)` method. For example, `builtInRoles.admin.can("project", "share")` returns a boolean indicating whether that role permits project sharing.

### Where are the permission tests located in the Kaneo repository?

Unit tests for role definitions reside in [`packages/permissions/src/index.test.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/permissions/src/index.test.ts), while end-to-end validation of RBAC behavior is implemented in [`tests/api-integration/workspace-rbac.test.ts`](https://github.com/usekaneo/kaneo/blob/main/tests/api-integration/workspace-rbac.test.ts). The package configuration for these tests is found in [`packages/permissions/vitest.config.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/permissions/vitest.config.ts).