Skip to content

Roles and Permissions

Applies to: All subscriptions

Purpose

State exactly what each role can do, so an administrator can map job functions to roles deliberately and answer access questions from documentation rather than by experiment.

Audience

System administrators, compliance and internal audit, implementation consultants.

Prerequisites

Reference

The nine roles

Role Purpose Transactional authority
Platform Super Admin Platform administration across tenants Full
Org Admin Configuration and user administration within an organisation None
Tax Controller The checker: commits tax documents Full for tax and logistics
Tax Executive The maker: prepares tax documents Prepare only
Approver Approval Engine sign-off, without processing rights None — invoice.approve and reads only
Finance Admin The fiscal calendar: lock and open years, seed the next, close and reopen periods None — fiscal.manage, gl.view and the universal reads only
Transport Manager Logistics operations e-Way Bill family only
Logistics Operator Logistics operations e-Way Bill family only
External Auditor Read-only assurance None

A system role is not an approval level

A user record carries two independent role fields. The system role above decides which API calls the holder may make. sys_user.approval_role_key decides which step of a multi-level approval they occupy — Finance Manager, Finance Controller, CFO and so on.

Approving in production requires both, and a user with only one is not an error state: nothing is logged, nothing is refused, the person is simply never asked. This is the single most common approval misconfiguration. See Segregation of Duties.

Permissions held by every role

These informational reads within the user's own tenant are held by all nine roles:

dashboard.view · notifications.view · intelligence.view · upload.view · template.view · audit.view

They are kept deliberately separate from resource-specific permissions such as admin.view, so that widening one cannot silently widen another.

Role by role

Platform Super Admin

Identifier super_admin. Named Platform Super Admin everywhere a person meets it — the Users & Roles picker, the role chip in the top bar, the Access tab and the Help Centre — because it is Complifly's own platform role, not a senior administrator inside a customer organisation. There is no separate tier below it.

Does not approve a customer's documents. Super Admin holds neither invoice.approve, tds.checker nor approval.override, so it cannot approve or force-approve an invoice or a TDS return, and a module switched off for a customer stays off for it too. Approving is the customer's decision; Super Admin operates the platform. Since 2026-10 it does hold admin.api (ERP delivery operations) and fiscal.manage (the fiscal calendar).

Platform-level administration, including across tenants. Holds the rest of the permission set: the full e-Invoice family, the full e-Way Bill and consolidated e-Way Bill families, reconciliation, master data, user administration, application reset and dataset deletion, template management including promotion, the full Invoice Generation family, numbering and ledger management.

Grant sparingly. This is the only role that reaches across tenant boundaries.

Org Admin

Configuration and administration without transactional authority. This separation is deliberate and is the design point of the role.

Holds Does not hold
admin.view, admin.manage_users, admin.reset_app Any irn.* action
admin.api — integration administration Any ewb.* or cewb.* action
approval.override — Force approve / Force reject, with a reason, never on a document they submitted Approving a level (invoice.approve), except when segregation of duties is off
masters.view Master data editing
numbering.manage — series definition is a configuration act Any invoice.* transactional action
gl.manage, gl.view — chart of accounts and posting rules fiscal.manage — an Org Admin can read the calendar but not lock, seed or close
mapping.edit — editing an ERP document's field transform rules
support.investigate — the Support Investigation screen, for their own company Any tds.* permission — an Org Admin does not see TDS data

An org admin controls who has access and how the system is configured, but cannot themselves commit a transaction.

Finance Admin

The role that runs the fiscal calendar, and nothing else. An Org Admin does not hold fiscal.manage, so your IT administrator can see which fiscal years are open but cannot lock one, seed the next, or close a period. To let someone do that, assign them Finance Admin in Users & Roles. It is a customer role, assigned by your Org Admin; Complifly Super Admin also holds the permission.

Holds Does not hold
fiscal.manage — Lock Year, Open Year, Seed Next Year, close and reopen a period, year-end close Any irn.*, ewb.*, invoice.* action
gl.view — read the ledger, the period list and the year-end pre-check gl.manage (chart of accounts, posting rules), admin.view, admin.manage_users
The universal reads Segregation-of-duties inheritance: switching SoD off does not give this role or its right to anyone

Before you upgrade

Until 2026-10-15, closing and reopening a period needed gl.manage, so an Org Admin could do it. After the upgrade they cannot. Assign Finance Admin to whoever closes your periods before the next month-end close, or the Close button will be missing for everyone except a Complifly Super Admin.

Tax Controller — the checker

Authority to finalise transactions.

Area Permissions
e-Invoice irn.create, irn.generate, irn.cancel, irn.decrypt, irn.print, irn.view
e-Way Bill The full family: create, generate, cancel, reject, extend, update Part-B, update transporter, multi-vehicle, change vehicle, distance, view
Consolidated e-Way Bill cewb.generate, cewb.regenerate, cewb.view
Reconciliation recon.view, recon.match
Masters masters.view, masters.edit, masters.customer.edit, masters.item.edit
Templates Upload, update, delete and promote
Invoice Generation The full family, including invoice.approve, invoice.issue, invoice.cancel
Ledger gl.view — reading the ledger and its reports. Configuring it is an administrative act
TDS tds.view, tds.manage, tds.checker — approve or reject a filed return. Not tds.maker

Approve, issue and cancel live only here. That placement is what makes the segregation model work.

Tax Executive — the maker

Can prepare and correct, but cannot commit.

Area Permissions
e-Invoice irn.create, irn.view, irn.decrypt, irn.print — not generate, not cancel
e-Way Bill ewb.view, ewb.get_distance only
Reconciliation recon.view, recon.match
Masters masters.view only
Templates Upload and update — not promote
Invoice Generation invoice.view, invoice.create, invoice.edit, invoice.print — not approve, issue or cancel
Ledger gl.view
TDS tds.view, tds.manage, tds.maker — prepare, validate and file a return. Not tds.checker

The absent permissions are the point of the role. A tax executive prepares work that a tax controller commits.

Approver — Approval Engine sign-off

Authority to clear an approval level, and nothing else. Added so that approval authority can be granted without transactional authority.

Area Permissions
Invoice Generation invoice.approve — approve or reject a level on a document awaiting sign-off
invoice.view, invoice.print — read the document and take a copy to review
e-Invoice irn.view — the IRN state behind a cancellation request
Masters masters.view — the customer and item the figures came from
Ledger gl.view — including GET /v1/gl/approval/config, the matrix that explains why the document routed to them

The approval role is a different thing, and grants no permission. The seven approval roles (Finance Executive to CFO) are a second field on the user record that only names which approval level the person may decide. They do not appear in the permission matrix below because they hold nothing in it. Approving a level needs three things together: a system role holding invoice.approve, an approval role equal to the one the level requires, and not being the person who submitted the document. An administrator is not exempt from the second — their route is an override (admin.api, Org Admin), which demands a reason and is recorded as Overridden.

It holds no create, edit, issue, cancel, generate, promote or administrative permission. The complete set is nine permissions plus the six universal reads.

Why this role exists

invoice.approve was previously held only by Tax Controller and Super Admin. A business head, plant head, director or CFO who had to clear an approval level therefore had two options, and both were wrong:

  • Make them a Tax Controller. That also grants invoice.create, invoice.edit, invoice.issue, invoice.cancel, irn.generate, irn.cancel, ewb.cancel, masters.edit and template.promote. An approver who can raise and issue the documents they sign off is not a control.
  • Grant nothing and use Force Approve. Every senior sign-off is then recorded as OVERRIDDEN with a bypass reason, which destroys the distinction between a real approval and an administrative override — the one thing the audit trail exists to preserve.

Assign Approver to people who sign off but do not process. Finance staff who do both keep Tax Controller, which still holds invoice.approve.

It is inert without an approval role

This role makes the Approve call reachable. It does not make a document arrive.

The workflow routes each level to the approval role that level requires and compares it against the caller's approval_role_key. A user with the Approver system role and no approval role assigned can open every document's workflow panel and act on none of them — with no error, because nothing has failed.

Assign both fields together. See Segregation of Duties for the approval-role ladder.

Transport Manager and Logistics Operator

Identical permission sets. Logistics only.

Holds Does not hold
The full e-Way Bill family Any IRN generation or cancellation
The consolidated e-Way Bill family Reconciliation matching
irn.view — for cross-checking Master data editing
masters.view

Two role names exist for organisational clarity — a manager and an operator may be distinct positions — while the authority is the same.

External Auditor

Zero-touch access. View and print only, across every area including administration and the ledger.

irn.view · ewb.view · cewb.view · recon.view · masters.view · admin.view · invoice.view · invoice.print · gl.view

Note the overlap with Approver, which holds a similar read set. The difference is invoice.approve: an auditor observes the workflow, an approver acts in it.

Designed so that granting audit access is never a risk decision.

Who may assign which role

Every role is either a platform role (Complifly's own, reaching across every customer) or a tenant role (yours). A role that is neither cannot be assigned by anyone.

Role Audience Who may assign it
Platform Super Admin (super_admin), Support Engineer (support_engineer), Platform Engineer (platform_engineer) Platform A Complifly Super Admin only
Org Admin, Finance Admin, Tax Controller, Tax Executive, Approver, Transport Manager, Logistics Operator, External Auditor Tenant Your Org Admin, or a Complifly Super Admin

The limit also works in reverse. Your Org Admin cannot edit, deactivate, delete or sign out a person who holds a platform role, even if that account sits in your company. If a person with a Complifly role appears in your user list and you did not expect them, tell Complifly support.

Internal Complifly roles

Two further roles exist only for Complifly's own staff. They cannot be assigned from your Users & Roles screen, are never held by a customer login, and no customer role grants them — they exist so a Complifly engineer can investigate a support ticket without being given ordinary access to your data. This is enforced by the server, not just hidden on the screen: an Org Admin who tries to assign one of them, by the screen or by calling the API directly, is refused and the attempt is recorded in your Audit Logs.

Role Identifier Access
Support Engineer support_engineer Read-only: documents, e-Invoices, e-Way Bills, reconciliation, Support Investigation, Compass and Operational Controls, to trace a reported failure, and the platform-wide Observability dashboards, which no customer role can open. No create, edit, cancel or approval rights, and cannot change users or settings.
Platform Engineer platform_engineer Read-only, narrower than Support Engineer: diagnosing an infrastructure or connectivity problem. Can also view Operational Controls and the platform-wide Observability dashboards.

A Compass investigation under either role is bound to one registration and recorded against the support ticket that authorised it. Either role can also view any company's Operational Controls, read-only; every such view is recorded in that company's audit log as OPERATIONAL_CONTROLS_VIEWED. If you see either name in an audit log entry, it identifies a Complifly-staff action taken while investigating a ticket you raised, not a role you granted.

TDS permissions are enforced by the server

Until 2026-10-02 the tds.* permissions were applied by the screens only: any signed-in user of an organisation with TDS enabled could call the TDS API directly. Every TDS request now requires tds.view, each write requires its own permission, and a return cannot be approved by the person who filed it (403 SELF_APPROVAL), whatever role they hold.

Action Permission Held by
Open TDS, read its data tds.view Tax Executive, Tax Controller, Platform Super Admin
Deductions, challans, notices, certificates tds.manage Tax Executive, Tax Controller, Platform Super Admin
Validate, generate FVU, upload CSI, file, start a correction tds.maker Tax Executive, Platform Super Admin
Approve or reject a filed return tds.checker Tax Controller
Create a TAN, change the deductor profile tds.admin Platform Super Admin

If your TDS users are Org Admins today, they lose TDS access with this release. Give them the Tax Executive or Tax Controller role before upgrading.

The complete permission matrix

The role descriptions above explain why the split is where it is. This table is the lookup underneath them: every permission the product grants, and which roles hold it.

Use it when you are handed a permission name. Hovering a greyed-out control in the product names the permission that would unlock it — for example ewb.update_partb. Search this table for that exact string, read across, and you have both the answer and the person to ask.

Permission Platform Super Admin Org Admin Tax Controller Tax Executive Transport Mgr Logistics Approver Finance Admin Auditor support_engineer platform_engineer
General
audit.view Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
dashboard.view Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
intelligence.view Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
notifications.view Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
upload.view Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
e-Invoice
irn.cancel Yes — Yes — — — — — — — —
irn.create Yes — Yes Yes — — — — — — —
irn.decrypt Yes — Yes Yes — — — — — — —
irn.generate Yes — Yes — — — — — — — —
irn.print Yes — Yes Yes — — — — — — —
irn.view Yes — Yes Yes Yes Yes Yes — Yes Yes Yes
e-Way Bill
ewb.cancel Yes — Yes — Yes Yes — — — — —
ewb.change_vehicle Yes — Yes — Yes Yes — — — — —
ewb.create Yes — Yes — Yes Yes — — — — —
ewb.extend Yes — Yes — Yes Yes — — — — —
ewb.generate Yes — Yes — Yes Yes — — — — —
ewb.get_distance Yes — Yes Yes Yes Yes — — — — —
ewb.multi_vehicle Yes — Yes — Yes Yes — — — — —
ewb.reject Yes — Yes — Yes Yes — — — — —
ewb.update_partb Yes — Yes — Yes Yes — — — — —
ewb.update_transporter Yes — Yes — Yes Yes — — — — —
ewb.view Yes — Yes Yes Yes Yes — — Yes Yes Yes
Consolidated e-Way Bill
cewb.generate Yes — Yes — Yes Yes — — — — —
cewb.regenerate Yes — Yes — Yes Yes — — — — —
cewb.view Yes — Yes — Yes Yes — — Yes Yes —
Invoice Generation
invoice.approve — — Yes — — — Yes — — — —
invoice.cancel Yes — Yes — — — — — — — —
invoice.create Yes — Yes Yes — — — — — — —
invoice.edit Yes — Yes Yes — — — — — — —
invoice.issue Yes — Yes — — — — — — — —
invoice.print Yes — Yes Yes — — Yes — Yes — —
invoice.view Yes — Yes Yes — — Yes — Yes Yes —
numbering.manage Yes Yes — — — — — — — — —
Ledger
fiscal.manage Yes — — — — — — Yes — — —
gl.manage Yes Yes — — — — — — — — —
gl.view Yes Yes Yes Yes — — Yes Yes Yes Yes —
Reconciliation
recon.match Yes — Yes Yes — — — — — — —
recon.view Yes — Yes Yes — — — — Yes Yes Yes
Master data
masters.customer.edit Yes — Yes — — — — — — — —
masters.edit Yes — Yes — — — — — — — —
masters.item.edit Yes — Yes — — — — — — — —
masters.view Yes Yes Yes Yes Yes Yes Yes — Yes Yes —
Mapping templates
template.delete Yes — Yes — — — — — — — —
template.promote Yes — Yes — — — — — — — —
template.update Yes — Yes Yes — — — — — — —
template.upload Yes — Yes Yes — — — — — — —
template.view Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Administration
admin.api Yes Yes — — — — — — — — —
admin.company_onboard Yes — — — — — — — — — —
admin.delete_datasets Yes — — — — — — — — — —
admin.manage_users Yes Yes — — — — — — — — —
admin.platform_config Yes — — — — — — — — — —
admin.reset_app Yes Yes — — — — — — — — —
admin.view Yes Yes — — — — — — Yes Yes Yes
admin.writeback_manage Yes — — — — — — — — — —
compliance_profile.manage Yes — — — — — — — — — —
compliance_profile.view Yes Yes — — — — — — Yes Yes Yes
housekeeping.legalhold.manage Yes — — — — — — — — — —
observability.platform Yes — — — — — — — — Yes Yes
support.investigate Yes Yes — — — — — — — Yes —
Other
agent.view Yes Yes — — — — — — — Yes Yes
agent_enrolment.approve Yes — — — — — — — — — —
agent_enrolment.request Yes Yes — — — — — — — — —
agent_entitlement.override Yes — — — — — — — — — —
approval.override — Yes — — — — — — — — —
attention.act Yes Yes Yes Yes Yes Yes — — — — —
attention.dispose Yes — Yes — Yes Yes — — — — —
compliance_declaration.manage Yes — — — — — — — — — —
compliance_declaration.view Yes Yes — — — — — — Yes Yes Yes
compliance_policy.attest Yes — — — — — — — — — —
compliance_policy.manage Yes — — — — — — — — — —
compliance_policy.view Yes Yes — — — — — — Yes Yes Yes
held_document.release Yes — — — — — — — — — —
mapping.edit Yes Yes — — — — — — — — —
scenario_declaration.attest Yes — — — — — — — — — —
scenario_declaration.manage Yes — — — — — — — — — —
scenario_declaration.view Yes Yes — — — — — — Yes Yes Yes
tds.admin Yes — — — — — — — — — —
tds.checker — — Yes — — — — — — — —
tds.maker Yes — — Yes — — — — — — —
tds.manage Yes — Yes Yes — — — — — — —
tds.view Yes — Yes Yes — — — — — — —

82 permissions across 11 roles. Generated from config/policies.js, the same module the API authorises against — do not edit this table by hand; run node tools/docs/gen-permission-matrix.js --write.

Mapping job functions to roles

Job function Role
IT administrator managing users and configuration Org Admin
Indirect tax manager approving and committing documents Tax Controller
Tax analyst preparing and correcting documents Tax Executive
Dispatch supervisor Transport Manager
Warehouse or dispatch clerk Logistics Operator
Internal or statutory auditor External Auditor
Complifly platform operations Super Admin

Map from what the person does, not from their job title. A "Finance Manager" may be a checker in one organisation and a preparer in another.

What is not configurable

Roles are fixed. There is no custom role builder and no per-user permission override. Access is shaped by three levers only:

  1. Which role a user holds
  2. Which registrations they may access
  3. Whether segregation of duties is enforced

Within Operational Controls, an organization administrator changes only the customer's business policies; settings that are part of the subscription are changed by Complifly. See Operational Controls.

This is a constraint worth stating early in an implementation, because customers frequently arrive expecting to define their own roles.

Validation

Check Method Pass condition
Every user has a deliberate role Review the user list with the process owner Each mapping justified
Maker cannot commit Sign in as a tax executive and attempt to generate an IRN Refused or greyed out
Org admin cannot transact Sign in as an org admin and attempt to generate an IRN Refused
Auditor cannot change anything Sign in as an auditor and attempt any action All refused
Logistics cannot generate IRNs Sign in as a logistics operator and attempt it Refused
Template promotion restricted Sign in as a tax executive and attempt to promote a template Refused
Approval restricted Sign in as a tax executive and attempt to approve an invoice Refused, when segregation is enforced
Access review scheduled Operations calendar Recurring, with a named owner

Perform these as real sign-in tests, not by reading the table. A permission that is documented but not enforced is a finding; a permission enforced but undocumented is a support cost.

Troubleshooting

Symptom Cause Action
"Why can my colleague do this and I cannot" Maker versus checker By design when segregation is enforced. Explain the model rather than changing the role
A user needs one extra permission No per-user overrides exist Either move them to the role that holds it, accepting everything else it grants, or keep the current role. There is no middle option
An org admin cannot generate an IRN By design — configuration authority excludes transactional authority If they genuinely need it, they need a different role, and the control consequence must be accepted
A tax executive can suddenly approve Segregation was relaxed Check the setting. See Segregation of Duties
Screen present but everything greyed out Role lacks the permissions Fix the role, not the feature flag
Screen entirely absent Feature flag, not role See Feature Flags
Screens load with no data GSTIN access See GSTIN Access Control
Customer wants a custom role Not supported Map to the closest role and document the gap. Escalate as a product request if material
Too many super admins Convenience during implementation Reduce to the minimum. Super Admin, Support Engineer and Platform Engineer are the cross-tenant roles, and only a Complifly Super Admin can assign them
Refused with PLATFORM_ROLE_REQUIRES_SUPER_ADMIN or PLATFORM_USER_NOT_MANAGEABLE An Org Admin tried to assign, or to change, a Complifly platform role Correct and permanent. See Who may assign which role

The Access tab

Admin & Logs > Access (called Permissions Matrix until October 2026) answers "who can do what, and why" in four views. It only reads: it never changes a role, a control or anyone's access.

View Question Who can open it
Roles What can each role click? Switch between SoD enforced and SoD relaxed to see which rights a role gains when segregation of duties is relaxed. The line beside the switch says which state the registration you are in is in now Org Admin, External Auditor, Complifly support and platform staff, Super Admin
Controls Who may change each operational control, who owns it (Complifly licensing, Complifly operations, or your organisation) and what changing it does to access (gates a module, widens roles, narrows roles, none) Same
Why can't they? Why is this person refused this action on this registration Same. A company's Org Admin and auditor can ask only about their own company
Review Who could approve, issue or administer on a given date, and what changed in a period. Downloads as CSV Same. Every run is recorded in the audit log

An External Auditor can open all four, read-only, as everywhere else. See Operational Controls for the owner classes.