Roles & Permissions

Keva defines role-based access control (RBAC) with 38 granular permissions across 12 groups. Selected product paths enforce these permissions locally; universal coverage, user-assignment UI, deployment, and product proof remain open.

Overview

The RBAC system consists of:

• Roles - Named sets of permissions
• Permissions - Granular access rights
• Assignments - Users assigned to roles

Default Role Templates

New organizations start with four system-role templates. These roles cannot be deleted, but authorized permission edits mean their stored permission sets can later differ from these defaults.

Permission Groups

This catalogue defines Keva's permission identifiers. A listed identifier does not by itself prove a connected UI action, universal route enforcement, or deployed behavior; for example, Settings > General exposes invite and pending-invitation revoke controls for authorized users with team.invite, while organization-member removal and Clerk membership-role changes remain outside this screen.

Tickets

Approvals

Knowledge Base

Settings

Team

Analytics

Billing

API Keys

Connectors

Automation

Audit

Custom Fields

Creating Custom Roles

1. Navigate to Settings > Roles
2. Click Add Role
3. Enter a name and description
4. Select a color for visual identification
5. Check the permissions to grant
6. Click Create Role

Editing Roles

1. Find the role in the list
2. Click Edit
3. Modify permissions as needed
4. Click Update Role

The DELETE /api/user-roles path rejects removing another user's sole remaining Owner assignment and rejects removing your own Owner assignment. Other role writers are not yet coordinated into a tenant-wide last-Owner guarantee. The current Settings screen does not expose tenant-role assignment controls.

System roles (Owner, Admin, Agent, Viewer) cannot be renamed, recolored, or deleted. Their permission sets are currently editable. The Owner role cannot be reduced to zero permissions.

Assigning Roles

Keva's tenant RBAC roles are separate from Clerk organization membership roles. The current Settings UI manages role definitions and their permissions, but does not expose a control for assigning these tenant RBAC roles to users.

Settings > Team displays the Clerk organization role (Admin or Member) as read-only. Clerk membership-role mutation is suspended in Keva and must use the approved Clerk administration process. The screen does not assign Owner, Admin, Agent, Viewer, or custom Keva tenant roles.

Default Permission Sets

Roles do not inherit from each other. New organizations start with these permission sets; authorized edits can change the stored system-role permissions:

Owner:  All 38 permissions
Admin:  All except billing.manage
Agent:  Tickets, approvals, KB, analytics
Viewer: View-only permissions

Best Practices

Start with Least Privilege

Begin with Viewer role and add permissions as needed rather than starting with Admin and removing.

Create Function-Specific Roles

Consider custom roles for specific functions:

• Support Lead: Agent + team.view
• KB Manager: kb.* + settings.view
• Billing Admin: billing.* + analytics.view

Regular Permission Audits

Review role assignments quarterly:

1. List all custom roles
2. Verify permissions are still appropriate
3. Reconcile user assignments through an approved administrative process
4. Remove unused custom roles

Document Custom Roles

Keep documentation of custom roles and their intended purpose for SOC 2 compliance.

Audit Trail

Role-management API mutations log these events:

• role.created - New role created
• role.updated - Role fields or permissions updated
• role.deleted - Role removed
• user_role.assigned - User assigned to role
• user_role.removed - User removed from role

This list does not claim that provisioning, Clerk membership lifecycle, or every direct writer emits the same per-role events.