Roles and permissions

Updated 31 May 2026·10 min read

TatvaCRM ships with five built-in roles and lets you build custom roles from a vocabulary of granular permissions. This page is the reference for what each role can do, how visibility scopes work, and when to create a custom role.

Two axes — what and whose

Every role in TatvaCRM is described by two independent axes:

Permissions — what actions the user can take. Read / write / delete on each entity type, plus management permissions for settings, roles, teams, custom fields, and so on.
Visibility scope — whose records the user can see.own (mine only), team (my team's), or everything (every record in the workspace).

Both axes are checked on every request. A user with the contacts:read permission and own visibility can read contacts — but only the ones they own.

The five system roles

Every tenant ships with these five roles. They are immutable — you cannot edit their permissions or visibility — which guarantees that documentation and screenshots in this guide always apply.

Role	Visibility	What it's for
Owner	`everything`	Workspace founder. All 51 permissions. The one person who can manage billing and delete the workspace.
Admin	`everything`	All permissions except the most destructive (workspace deletion, plan changes). Use for ops / RevOps / sales leadership.
Manager	`team`	CRUD on records owned by their team — including export. Cannot touch settings or roles. Use for line managers running a team of reps.
Member	`own`	Read + write on records they own. No delete, no export by default. Use for individual contributors — sales reps, support agents.
Viewer	`own`	Read-only on records they own. No writes, no exports. Use for stakeholders who need to see but not touch — finance, an external consultant.

Always have at least two Owners

Set up a second Owner the moment your first invite goes out. Single-Owner workspaces are one lost laptop away from a bad week — and only Owners can re-promote another user to Owner.

Visibility scopes in detail

own

The user sees only records where they are the owner. Other users' records — even teammates' — are completely hidden. Search returns no results for someone else's contact. The detail page returns 404.

Activities work slightly differently. A user with own visibility on activities can still see an activity they personally performed (a note they wrote, a call they logged) even if the parent record belongs to someone else. This is intentional — reps need to see their own work.

team

The user sees records owned by anyone in their team. Team membership is set in Settings → Team. A user with team visibility on contacts who belongs to the "Mumbai" team sees every contact whose owner is in the Mumbai team.

A user can be in multiple teams. In that case team visibility is the union — they see records owned by any of their teams.

everything

The user sees every record in the workspace, regardless of owner. This is the default for Owner and Admin.

Unassigned records

Records with no owner are visible only to everything-scoped users. After a bulk import or webform capture, set an owner before the records get lost to own / team users. The import flow has an Assign owner step for this reason.

Permission vocabulary

Permissions follow a consistent naming pattern: <entity>:<action>. The actions are read, write, delete,export, import for most entities, with some entity-specific actions (leads:convert, commissions:approve).

Core CRM permissions (Phase 1)

contacts:read, contacts:write, contacts:delete, contacts:export, contacts:import
companies:read, companies:write, companies:delete, companies:export, companies:import
deals:read, deals:write, deals:delete, deals:export, deals:import
leads:read, leads:write, leads:delete, leads:convert, leads:export, leads:import
tasks:read, tasks:write, tasks:delete, tasks:export, tasks:import
activities:read, activities:write, activities:delete
pipelines:read, pipelines:manage
custom_fields:manage, picklists:read, picklists:write
team:read, team:manage, team:invite
roles:read, roles:manage
teams:read, teams:manage
settings:read, settings:manage
reports:read, audit:read
emails:read, emails:write
documents:read, documents:write
import:run, import_history:read

Industry-overlay permissions (lenders, sub-DSAs, commissions, payout grids, loan documents) ship with the BFSI presets and are documented under By industry when each preset goes live.

Custom roles

If the five system roles don't fit, you can build a custom role with any combination of permissions and a per-module visibility scope. Common cases we see:

Sales Ops — like Manager but with everything scope and reports:read on every entity
Support Agent — read-only on contacts + deals, write on tasks + activities
Junior Rep — like Member but without delete permissions

Create custom roles at Settings → Roles → New role. Custom roles can be edited and deleted; system roles cannot.

JWT propagation

Permissions and visibility are baked into the user's JWT at login time. When you change a user's role, the new permissions take effect on their next JWT refresh — which by default is at most 15 minutes. If you need an immediate cut-over (e.g. revoking access for a terminated employee), have the user log out and back in, or kick their session from Settings → Team → Active sessions.

Who can manage roles

The roles:manage permission gates the Roles page. By default, only Owner and Admin have it. Manager can read the roles list (so they know who has what) but cannot edit.

You cannot change your own role to one that would lock you out — TatvaCRM blocks this. You also cannot delete the last user with the Owner role. If you genuinely need to step away, promote another user to Owner first.

What next

Teams and visibility — how to structure teams so the team scope behaves correctly
Contacts overview — see the visibility rules in action

← PreviousOverview

Was this page helpful?

Anonymous · we read every response

👍 Yes 👎 No