Skip to content

Login and Access Failures

Applies to: All subscriptions

Purpose

Resolve the largest single category of first-line tickets: someone cannot sign in, or signs in and cannot do what they expect. Most of these are not authentication faults, and the tree below separates them quickly.

Audience

First-line support, administrators.

Prerequisites

  • The user's identity and the exact message
  • Administrator access to the user list

Steps

The decision tree

  A user reports an access problem
        |
        v
  Can they sign in at all?
        |
        +-- No --> Does it say the company is ARCHIVED?  -> Path G
        |          Otherwise: is it one person or several?
        |            |
        |            +-- Several --> CHECK MAIL FIRST. -> Path A
        |            |                Password reset and one-time codes both
        |            |                depend on email. This is the most common
        |            |                cause and the least obvious
        |            |
        |            +-- One ------> Account state, password, lockout. -> Path B
        |
        +-- Yes -> What are they seeing?
                     |
                     +-- Whole module absent -----> Feature flag. -> Path C
                     |
                     +-- Controls greyed out -----> Role permission. -> Path D
                     |
                     +-- Screen loads, no data ---> Registration access. -> Path E

Before you work through a path, ask the system. In Admin & Logs > Access > Why can't they? choose the person, the action and the registration. It walks the gates in the order a request meets them and says which refuses, who owns it and when a change would apply. For the three "signed in but blocked" branches below it usually names the path for you: role is Path D, registration is not in the access list is Path E, module is switched off is Path C. An Org Admin or an auditor can ask about their own company; Complifly support can ask about any (recorded in that customer's audit log). It explains, it does not change anything.

The three "signed in but blocked" branches look similar to a user and are entirely different problems. Ask which of the three they are seeing — a single question that usually ends the investigation.

Path 0 — "Too many failed attempts. Please try again in 15 minutes."

Step Action
Symptoms Sign-in answers HTTP 429 with that message, even with the right password
Root cause The authentication throttle: more than 20 failed requests from one client address in 15 minutes (AUTH_RATE_LIMIT_MAX). Successful sign-ins do not count, but every failure from a shared office address does
Checks Observability > Security — Authentication: Blocked by rate limit (24h), Top source addresses. Is one address (a shared NAT, a script with a stale password) responsible?
Resolution Wait 15 minutes. Fix the cause (stale saved password, a service account with an old credential). Do not disable the throttle in production
Validation The user signs in; Blocked by rate limit stops rising
Escalate when Many different addresses are failing against the same accounts — treat as password guessing

Path A — several users cannot sign in

Step Action
Symptoms Multiple users blocked, often reporting that reset emails never arrive
Root cause Mail delivery. Password reset, one-time codes and account activation all depend on it
Checks Send a test message to a known-good mailbox. Check the mail path from the application host. Check spam filtering. Check the sending host is not on a block list
Resolution Fix the mail configuration or the path
Validation A password reset is delivered to a real inbox and completes
Escalate when Mail is proven working and users are still blocked

Nothing errors when mail fails. The application starts normally, the interface shows nothing wrong, and the ticket says "I cannot log in" — which sends the responder to authentication instead of to mail.

Path B — one user cannot sign in

Step Action
Symptoms One person blocked
Root cause Wrong password, locked out, account disabled, never activated, or an external identity provider problem
Checks Does the account exist and is it enabled? Was it ever activated? Is it locked out? Is the email address correct? Does the identity provider report a problem?
Resolution Reset, unlock, enable, or correct the address
Validation The user signs in
Escalate when The account is enabled, activated and unlocked, and sign-in still fails

A person who was working is suddenly sent to the sign-in page. The sign-in page now says why when an administrator caused it. Match the sentence to the cause:

The sign-in page says Cause Action
"Your account has been deactivated" An administrator disabled the account Re-enable it if that was a mistake. Check UPDATE_USER in the audit log for who and when
"Your role was changed" or "Your access was changed" An administrator edited the role, approval role or GSTIN access; the edit signs the person out so it applies at once Expected. The person signs in again. If the edit was not intended, correct it, then check UPDATE_USER and SESSIONS_REVOKED
"An administrator ended this session" Someone used End sessions on this person Expected. The person signs in again
The generic "This session has been signed out" The person signed out elsewhere, or signed in on another device and ended this one Nothing to fix. See User Authentication

Path C — a whole module is absent

Step Action
Symptoms No navigation entry for the module at all
Root cause The feature is not enabled for that registration
Checks Is it licensed? Is the flag set for this registration? Was it set recently — flags cache briefly
Resolution Enable it for the correct registration
Validation The module appears and opens
Escalate when Enabled, cache expired, still absent

Check every registration, not only the one you are signed in to. Flags are per registration.

Path D — controls are greyed out

Step Action
Symptoms The screen is there; buttons are disabled
Root cause The role does not hold the permission — frequently by design, under segregation of duties
Checks Which role does the user hold? Does it hold the permission? Is segregation enforced? Access > Roles shows the table with segregation of duties enforced or relaxed; Access > Why can't they? answers it for this person and action
Resolution Move them to the role that holds it, accepting everything else that role grants. There are no per-user overrides
Validation The control is enabled
Escalate when The role should hold it per the documentation and does not

"Why can my colleague do this and I cannot" is nearly always maker versus checker. That is the control working, not a fault.

Path E — the screen loads with no data

Step Action
Symptoms Screens render correctly and are empty
Root cause The user has no access to the registration whose data they expect
Checks Which registrations does the user hold access to? Which one holds the data?
Resolution Grant access to the correct registration
Validation Data appears
Escalate when Access is granted to the correct registration and data is still absent

This is the branch most often reported as "the system has lost our data". It has not.

Path F — an approver is never asked to approve

Step Action
Symptoms The person is supposed to sign off and nothing reaches them, or the Approval workflow panel is visible with no Approve button
Root cause One of the two role fields is missing. A user record carries a system role (may they call approve?) and an approval role (which level are they?) and needs both
Checks On the user record: does the system role hold invoice.approve — i.e. is it Approver or Tax Controller? Is an approval role assigned? Does it match the level the document is waiting on?
Resolution Assign whichever field is missing. Both are on Administration > Admin & Logs > Users & Roles
Validation Open a document pending at their level; Approve and Reject appear and succeed
Escalate when Both fields are correct and the document still does not offer the action

This branch is silent by construction. Neither missing field is an error: the account exists, the person signs in, every screen works, and no log line says anything is wrong. That is why it is reported as "approvals are broken" rather than as an access problem.

Three things this is not, before you go looking:

Not this Why
An earlier level has not acted Approvals are sequential and the panel names who it is waiting on. Nothing is wrong
They submitted the document themselves Nobody can decide a document they submitted, whatever role they hold. Not waivable, not a misconfiguration
An administrator could just approve it instead They cannot. There is no administrative exemption on the level check. The supported path is Force approve, which demands a reason and records the level as Overridden

The other half of this branch is a level with no holder at all. Nothing validates that every approval role your matrix uses is assigned to somebody, so a document can route to a level nobody occupies and sit there indefinitely. Check the matrix against the user list, and give each level in use at least two holders.

Path G — "This company has been archived"

Step Action
Symptoms Every user of the company is refused at sign-in with This company has been archived. (403 TENANT_ARCHIVED); users already signed in get the same message on every screen; the ERP's document intake returns 403 TENANT_ARCHIVED
Root cause A Complifly Super Admin archived the company. This is never automatic — it is not caused by a plan limit, volume or payment
Checks Was an offboarding or ownership change planned? Ask Complifly for the recorded reason, who set it and when
Resolution If unintended, Complifly reactivates the company with a recorded reason. No data needs restoring
Validation Users sign in; the ERP's next document is accepted
Escalate when Always — an administrator of the customer cannot change a company's status

A suspended company is not in this path: its users sign in and work normally. A suspension only blocks adding a user, API key, ERP connection or registration (409 TENANT_SUSPENDED). See Company Status.

Validation

Check Pass condition
The branch was identified Absent, greyed, or empty — established by asking
Mail checked first for multi-user cases Before authentication was investigated
The fix matches the gate Flag, role or access — not a guess
Verified as the user Confirmed by signing in as them, or by their confirmation
Attribution preserved Departed users disabled, never deleted

Troubleshooting

Symptom Cause Action
Several users blocked at once Mail delivery Check mail before authentication
Reset email never arrives Mail, wrong address, or spam filtering Test to a known-good mailbox
One-time code arrives too late Relay latency exceeds the code's validity Reduce latency or extend the lifetime deliberately
Everyone signed out at once The token signing secret changed Expected if intended; investigate if not
Every user refused, message says the company is archived The company is archived Path G; only Complifly can reactivate it
Signs in and sees nothing No registration access Grant it
Everything greyed out Role lacks the permissions Fix the role
A module is entirely missing Feature flag Enable it for that registration
A user needs one extra permission No per-user overrides exist Change the role, or accept the limitation
An approver sees the workflow but no Approve button System role lacks invoice.approve Assign the Approver or Tax Controller system role
An approver can approve but nothing reaches them No approval role assigned, or the wrong one Assign the approval role naming their level
A document is stuck PENDING and nobody can act The level names an approval role no active user holds Assign that approval role to somebody; keep two holders per level
An administrator cannot approve on someone's behalf No administrative exemption on the level check, by design Use Force approve with a written reason, or have a real holder decide
A user cannot approve their own document Self-approval is blocked on identity Correct behaviour. Not fixable by any role change
Nobody can administer the system The sole administrator is unavailable Always maintain two
A departed user's history is gone The account was deleted Disable, never delete
External sign-in redirect fails Redirect URL not registered, or a protocol mismatch Register the exact URL