Troubleshooting

Common user management, RBAC, and authentication issues

Use this guide to quickly diagnose invitation failures, permission mismatches, and authentication/session issues.

Triage Flow

Invitation Issues

User stays in invited

Cause: User has not completed initial login and password setup.

Fix:

1. Resend invitation.
2. Confirm email delivery path and spam filtering.
3. Validate account is not deactivated.

Invite created but wrong role/scopes

Cause: Incorrect role selected during creation.

Fix:

1. Open user details.
2. Update role and permissions.
3. Re-test with a clean session.

Permission Issues

User cannot access a module

Cause: Missing resource:view or resource:manage scope.

Fix:

1. Check assigned global scopes.
2. Add missing scope.
3. Ask user to refresh session/sign in again.

User can open project but cannot modify resources

Cause: Project-level permission is view only.

Fix: Upgrade project permission to manage if justified.

Authentication Issues

Repeated sign-out or session loops

Cause: Access token expiry plus refresh failure.

Fix:

1. Confirm refresh token endpoint health.
2. Verify local token storage is intact.
3. Clear local session and re-authenticate.

401/403 after role update

Cause: Old token still carries previous claims.

Fix: Force logout/login to refresh effective permissions.

Operational Best Practices

Keep privileged scopes minimal and time-bound.

Review inactive and invited users on a schedule.

Use explicit project sharing instead of broad global manage scopes.