Roles and permissions in TatvaCRM

Roles and permissions in TatvaCRM answer two questions about every team member: what can they do, and whose records can they see. This page is the reference for the five built-in roles, what each one can do, how visibility scopes work, and when to build a custom role instead.

The two axes — what and whose

Every role is described by two independent things:

• Permissions — what actions the user can take. Read, add, edit, delete, export, import, manage settings, and so on. Each module (contacts, deals, leads, etc.) has its own set.
• Visibility scope — whose records the user can see. Three values: own (mine only), team (my team’s), everything (all records in the workspace).

Both are checked on every request. A user with contacts.read and own visibility can read contacts — but only the ones they own. Someone else’s contacts return “not found”, even if they exist.

The five built-in roles

Every workspace ships with these five. They cannot be edited or deleted — guaranteeing that any documentation or guide you read will always apply identically across all workspaces.

How the three visibility scopes work

own — sees only their own records

The user sees only records where they are the owner. Others’ records — including 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 underlying contact belongs to someone else. This is intentional — reps need to see their own work.

team — sees their team’s records

The user sees records owned by anyone in their team. Teams are set up at Settings → Teams. 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 belong to multiple teams. In that case team visibility is the union — they see records owned by any member of any of their teams.

everything — sees every record

The user sees every record in the workspace, regardless of owner. This is the default for Owner and Admin and most admin-style custom roles.

What permissions exist?

Permissions follow a consistent pattern: <module>.<action>. Common actions across most modules:

• read — view the records
• create — add new records
• edit — modify existing records
• delete — soft-delete (records can be restored from Recycle Bin within 30 days)
• export — download as CSV / Excel
• import — bulk-import from CSV

Modules covered in Phase 1 (Core CRM):

• contacts.* — manage contacts
• companies.* — manage companies
• deals.* — manage deals (plus deals.move for stage transitions)
• leads.* — manage leads (plus leads.convert for conversions)
• tasks.* — manage tasks
• activities.* — log and view activities
• pipelines.read, pipelines.manage — view and edit pipeline configuration
• custom_fields.manage — add, edit, remove custom fields on any module
• team.invite, team.manage — manage team members
• roles.read, roles.manage — view and manage roles
• teams.read, teams.manage — view and manage teams
• settings.read, settings.manage — view and edit workspace settings
• reports.read, reports.create — view and build reports
• files.read, files.write — manage attached files

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.

When and how to create a custom role

If none of the five built-in roles fit, build a custom role. Common cases we see in Indian SMB sales teams:

• Sales Operations — like Manager, but with everything scope and full export rights on every entity
• Support Agent — read-only on contacts and deals, full write on tasks and activities
• Junior Sales Rep — like Member, but without delete permissions
• Finance reviewer — read on deals, full read on reports, nothing else
• Outsourced telecaller — write on tasks and activities, read on contacts, no access to deals or revenue numbers

Create custom roles at Settings → Roles → New role. Custom roles can be edited and deleted at any time. The five built-in roles cannot.

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 which role each team member is on) but cannot edit roles or change someone’s role.

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

Practical example: StoreWorks’ sales team

Aditya at StoreWorks runs his ten-person sales org with this setup:

Each role choice maps to a real business need. SDRs as Members because they shouldn’t see other reps’ leads (it changes their behaviour). AEs as Managers because they need to see their pod’s deals and coach the SDRs handing off to them. Anant as a custom Sales Ops role because no built-in role does “see everything but cannot manage roles or settings.”

Common questions

“How do I make someone else an Owner?”

Settings → Team → click on the user → change role to Owner. Only an existing Owner can promote someone to Owner. Demote yourself afterwards if you don’t want to remain Owner — just don’t demote the only remaining Owner.

“Can a user have more than one role?”

No — each user has exactly one role per workspace. The same person can have a different role in a different workspace (e.g. Owner of their own workspace, Manager in a client’s workspace where they’re consulting).

“Can I restrict a user to only seeing deals under ₹10 Lakh?”

Not directly through role and visibility — those work on owner-based rules, not value-based rules. If you need value-based restrictions, set them up via the Filter view that becomes the user’s default view (set per user via Settings → User defaults). Hidden vs not-allowed are different things — the user could theoretically clear the filter — so this works only for visual defaults, not security boundaries.

“Someone needs temporary access for a few days. How do I do that?”

Set them up with a custom role limited to what they need. After their work is done, change their role to Viewer (read-only) or remove them entirely from Settings → Team → Remove user. Removing the user revokes access immediately and frees up a seat. The contacts they were the owner of get reassigned to whoever you choose during the removal.

“If I have contacts.delete, can I bypass the 30-day Recycle Bin?”

No. The contacts.delete permission performs a soft delete and moves the record to the Recycle Bin. Permanent deletion (purge) happens after 30 days automatically. Even Owners cannot force-purge a record before then — this protects against an irreversible mistake.

What to read next

• Teams and visibility — set up teams so the team scope behaves the way you want
• Invite your team — the practical onboarding
• Contacts — overview — visibility in practice on the Contacts module