Skip to content

GSTIN Access Control

Applies to: All subscriptions

Purpose

Explain the third access gate — which registrations a user may work with — and how it differs from their role. This gate produces the most confusing symptom in the product: screens that load correctly and show nothing.

Audience

System administrators, security reviewers, first-line support.

Prerequisites

Reference

Why it is separate from the role

A role answers what may this person do. GSTIN access answers to which registrations. They are orthogonal, and both are needed.

A tax controller at a Karnataka site and a tax controller at a Maharashtra site hold identical authority and must not see each other's documents. One role, two access sets.

How it works

Each user is granted access to one or more registrations. Every request carries the registration being worked on, and the platform:

  1. Confirms the user holds access to it.
  2. Applies that scope to every query.
  3. Relies on database-level policies to filter rows even if a query were written without the filter.

The scope is derived from the verified identity, never from client input. That property is what stops the tier being a privilege-escalation path, and it is worth stating explicitly to a security reviewer.

The symptom this gate produces

Gate Symptom
Feature flag The whole screen is absent
Role permission The screen is present; controls are greyed out
GSTIN access Screens load correctly and show no data

The third is the one that gets reported as "the system is broken" or "our data has been lost". It is neither. Check GSTIN access before investigating anything else when a user reports missing data.

Granting access, step by step

Access is assigned per user, in Administration → Users & Roles.

1. Open the user

Select Add User for a new person, or open an existing user to edit them.

2. Choose the company

For a Super Admin creating a user across companies, choose the company first. The registration list below is populated from it, and switching company clears any selection already made — so do this before picking registrations, not after.

3. Set the Default GSTIN

Pick the registration the user works in most. It becomes the one their session opens on.

The default is automatically included in the authorised set and its tick cannot be removed. You do not need to select it again in step 4.

4. Tick the Authorized GSTIN Registrations

In the Authorized GSTIN Registrations list, tick every additional registration this person may work in.

Grant the minimum that lets them do their job:

Principle Reason
Grant the minimum A user at one site rarely needs group-wide visibility
Include dormant registrations only if they will be used An unused grant is unnecessary exposure
Group-wide access is a decision Legitimate for consolidated reporting — but make it deliberately, not by ticking everything

5. Save

Editing a user replaces the whole access set

Saving an existing user does not merge the ticked registrations with what they already had — it replaces the set with exactly what is ticked in the dialog. Open the user, confirm the current ticks reflect what they should keep, and then add to them. Saving with a partially loaded list silently removes the rest.

6. Verify from the user's side

Check: have the user sign in and confirm the registration switcher lists exactly the intended registrations, and that a screen scoped to one of them shows data.

This is the only check that proves it. An access set that is wrong does not produce an error anywhere — see The symptom this gate produces above.

7. Review when people move

Access accumulates across role changes and is rarely trimmed. Re-run steps 1 to 6 whenever someone changes site, function or employer status, and treat a leaver as a deactivation rather than an access edit.

Cross-tenant access

A platform-level bypass exists for genuine cross-tenant administration. It is deliberately narrow, should be held by very few identities, and its use should be visible in the audit trail. Treat any request to widen it as a security decision, not a convenience.

How it interacts with machine credentials

Machine credentials carry their own GSTIN scope, independent of any user. An ERP credential can submit documents only for the registrations in its scope, regardless of what the users of that ERP can see.

Identity Scope source
A person The registrations granted to their account
An ERP The scope on the credential

This is why a forbidden response on ingest is a credential-scope question, not a user-permission question — a distinction that saves considerable diagnostic time.

Validation

Check Method Pass condition
Access is granted correctly Sign in as the user Only the intended registrations are available
Data is scoped Open a list screen Only that registration's documents appear
Cross-registration access is blocked Attempt to open a document from a registration the user lacks Not found
Scope is server-derived Alter a client-supplied identifier in a request The result does not change
Removal takes effect Remove access and reload Data no longer visible
Machine credential scope enforced Submit a document for an out-of-scope registration Refused as forbidden
Cross-tenant bypass is minimal Review who holds it Very few identities, each justified
Access is minimal overall Review every user's grants No unexplained group-wide access

The cross-registration test needs two registrations and one user. It is the single most useful check on this page, and it is skipped because it needs a moment of setup.

Troubleshooting

Symptom Cause Action
User signs in and sees no data No GSTIN access granted Grant it. This is the most common cause of "the system is empty"
User sees fewer documents than expected Access to some registrations missing Compare granted access against the registrations they work with
User sees data they should not Over-broad grant, or a cross-tenant bypass held unnecessarily Trim the grant. If it is a bypass, treat it as a security review item
Data disappeared after a role change GSTIN access changed at the same time The two are separate; check both
A report is empty for a period with data Query run without scope, or run by a user without access Check access first, then the query. See Multi-Tenancy and Row-Level Security
Ingest refused as forbidden The document's supplier registration is outside the credential's scope Fix the credential scope, not the user's access
A newly onboarded registration is invisible Nobody has been granted access to it Grant access after onboarding a registration; it is easily forgotten
A dormant registration issues a document and it is rejected The registration was never onboarded Onboard it. This is why dormant registrations belong on the initial list
An external reporting tool returns nothing Connects without setting scope Use the supported reporting pattern. Never disable isolation policies