Skip to main content
Version: Next

Troubleshooting permissions

This guide provides solutions for common permission and access control issues. Use it when users report problems accessing features or data.


Quick diagnosis checklist

Before diving into specific issues, verify these basics:

  • User account is active (isActive: true)
  • User has logged in recently (session valid)
  • User has at least one role assigned
  • Correct school/organization is selected
  • No active account lock (lockedUntil)

Common issues and solutions

Issue: User cannot see a menu item

Symptoms:

  • Navigation menu missing expected item
  • Tab or section not visible
  • Feature appears hidden

Diagnosis:

  1. Check user's assigned roles:

    Users → [User] → Roles tab
  2. Verify role has the required permission:

    Roles → [Role] → Permissions tab
  3. Check the permission needed:

    Menu itemRequired permission
    Studentsstudents.view
    Teachersteachers.view
    Financefinance.view
    Settingssettings.view
    Usersusers.view
    Auditaudit.view

Solution:

  • Add missing permission to role, OR
  • Assign additional role with permission, OR
  • Create custom role with needed access

Issue: "Access denied" error

Symptoms:

  • Error message when clicking button
  • Action fails with permission error
  • Form submission rejected

Diagnosis:

  1. Note the exact action attempted
  2. Check user's effective permissions:
    Users → [User] → Permissions tab → View effective
  3. Verify permission source (role vs direct)

Common causes:

CauseFix
Permission not grantedAdd to role
Wrong scope selectedSelect correct school
Role assignment expiredRenew assignment
Policy blockingReview ABAC policies

Solution:

  • Identify the specific permission needed
  • Grant via role (preferred) or directly

Issue: User can view but cannot edit

Symptoms:

  • Data displays but fields are read-only
  • Edit button missing or disabled
  • Save button doesn't appear

Explanation:

View and edit are separate permissions:

  • resource.view — Read access only
  • resource.update — Edit access needed

Solution:

  • Add the *.update permission for the resource
  • Or assign a role that includes edit access

Issue: User can see some records but not others

Symptoms:

  • Partial data visible
  • "Record not found" for specific items
  • Different results than admin sees

Diagnosis:

This usually indicates scoped access:

  1. Organization scope — User may only see records in their school/department
  2. Resource grants — Access limited to specific instances
  3. ABAC policy — Conditional rules filtering data

Check:

Users → [User] → Role assignments
→ Verify organization unit scope

Solution:

  • Expand organization scope, OR
  • Grant access to specific resources, OR
  • Review/adjust ABAC policies

Issue: New role not taking effect

Symptoms:

  • Role assigned but permissions don't work
  • User still has old access level
  • Changes not reflected

Diagnosis:

  1. Assignment not active

    Check: isActive = true on assignment
  2. Assignment expired

    Check: expiresAt (if set)
  3. Session cache

    User needs to log out and back in
  4. Wrong organization scope

    Role may be scoped to different school

Solution:

  • Verify assignment is active and not expired
  • Have user log out and back in
  • Check organization unit matches context

Issue: Permission worked before, now doesn't

Symptoms:

  • Feature used to work
  • Now getting access denied
  • No obvious change

Possible causes:

CauseHow to check
Role modifiedAudit logs → Role changes
Permission removedRoles → [Role] → Permissions
Assignment expiredUsers → [User] → Roles
Policy changedPolicies → Recent changes
Account status changedUsers → [User] → Status

Solution:

  • Review audit log for recent changes
  • Restore permission or assignment as needed

Issue: Cannot access other school's data

Symptoms:

  • User is admin but can't see other school
  • Data visible in one school, not another
  • Cross-school features don't work

Explanation:

Access is typically scoped by organization:

Tenant Admin → All schools
School Admin → Only their school(s)
Teacher → Only their school

Solution:

  • For Tenant Admin access: Assign Tenant Admin role
  • For specific school: Add role with that school scope
  • For temporary: Use resource grants

Issue: Guardian cannot see child's data

Symptoms:

  • Parent logged in but no student data
  • "No students linked" message
  • Guardian portal empty

Diagnosis:

  1. Verify guardian-student link:

    Students → [Student] → Guardians tab
  2. Check guardian account is active

  3. Verify guardian role assigned

Solution:

  • Link guardian to student record
  • Activate guardian account
  • Assign Guardian role

Issue: Student cannot access portal

Symptoms:

  • Student login fails
  • Portal shows no data
  • Access denied messages

Checklist:

  1. Student user account exists
  2. Account is active
  3. Student role assigned
  4. Student record linked to user
  5. Enrollment is current

Solution:

  • Create/activate user account
  • Link to student record
  • Verify current enrollment

Issue: MFA blocking access

Symptoms:

  • Login succeeds but MFA fails
  • "MFA required" but can't complete
  • Locked out after MFA attempts

Solutions by scenario:

ScenarioSolution
Lost authenticatorUse backup codes
No backup codesAdmin reset MFA
SMS not receivedCheck phone number, try again
TOTP wrong codeSync device time

Admin reset MFA:

Users → [User] → Security → Reset MFA

Issue: Session terminated unexpectedly

Symptoms:

  • Logged out without warning
  • Work lost
  • Frequent re-authentication

Possible causes:

CauseFix
Idle timeoutWork within timeout or request extension
Session limitCheck max sessions setting
Admin terminatedContact admin
Security policyReview login location/device
Token refresh failedClear cookies, log in fresh

Issue: Device not recognized

Symptoms:

  • "Unknown device" warnings
  • Extra verification required
  • Device trust prompts

Explanation:

Device fingerprint changed due to:

  • Browser update
  • Cleared cookies
  • Incognito mode
  • VPN change

Solution:

  • Trust the device when prompted
  • For frequent use, avoid incognito
  • Maintain consistent VPN usage

Debugging permission issues

Step 1: Identify the permission

Determine what permission is needed:

  1. Note the exact action failing
  2. Check documentation for required permission
  3. Look in browser console for permission name

Step 2: Check user's permissions

View effective permissions:

Foundation → IAM → Users → [User] → Permissions

The "Effective Permissions" view shows:

  • All permissions user has
  • Source (which role)
  • Direct assignments

Step 3: Trace the permission path

For missing permission:

Is permission in any user's role?
No → Add to role or assign role with it

Yes → Is role assigned to user?
No → Assign the role

Yes → Is assignment active?
No → Activate or renew

Yes → Is scope correct?
No → Adjust organization scope

Yes → Check ABAC policies

Step 4: Check for denials

ABAC policies can explicitly deny:

Foundation → IAM → Policies
Filter: effect = deny

A deny policy overrides all grants.

Step 5: Review audit log

Check what changed:

Foundation → Audit → Logs
Filter: resource = users OR roles OR permissions
Filter: user = [affected user]

Permission error messages

Error messageMeaningSolution
"Permission denied"Missing required permissionAdd permission
"Access denied"Authorization failedCheck role/scope
"Not authorized"Not logged in or session invalidRe-authenticate
"Forbidden"Server rejected requestCheck all permission layers
"Resource not found"May be access scope issueCheck organization scope

Escalation path

If you cannot resolve:

  1. Document the issue:

    • User email/ID
    • Exact action attempted
    • Exact error message
    • Current roles and permissions
  2. Check for related:

    • Is this one user or multiple?
    • Is this one action or multiple?
    • When did it start?
  3. Escalate with:

    • Screenshots
    • Audit log excerpts
    • Steps to reproduce

Preventive measures

Regular audits

  • Monthly: Review active user count
  • Quarterly: Review role assignments
  • Quarterly: Review custom roles
  • Annually: Full permission audit

Change management

  • Document permission changes
  • Test changes with sample user
  • Notify affected users
  • Keep rollback plan

User training

  • Explain role-based access
  • Document how to request access
  • Provide self-service where appropriate