Access Troubleshooting

Audience: support engineers, admins Difficulty: admin only

What this covers

The most common login and workspace-access dead-ends, plus the SSO handoff between the parent app and Solabooks. Each row gives a concrete check or fix.

The login chain (parent app)

/login → POST /login → Authenticated session → SetClientContext →
  EnsureWorkspaceOnboardingCompleted → /portal/orgs (or /admin)

A user can break out of this chain at five points. Diagnose by where the redirect lands.

Spatie roles vs. user_organizations.role

Two parallel role systems live on the parent app — understand both.

Spatie role. Stored in model_has_roles. Examples: super-admin, admin, client_owner, client_manager, client_member. Checked by Blade @hasrole, route role: middleware, AdminPolicy::before().

user_organizations.role column. A free-form string column. Used by SuperAdminProvisioningSeeder (writes 'client_owner') and by some controllers when scoping per-org behaviour. Not the same as the Spatie role.

For full access a user needs both:

• The Spatie role that matches their level (client_owner for owners).
• A user_organizations row with the correct role string.

Common mismatch: the user is granted Spatie client_owner but their user_organizations.role is still client_member. They see the correct UI affordances but per-org operations fail.

Fix. From /admin/clients > [client] > Members, click the user and re-pick the role. The UI writes both.

Solabooks app role chain

The finance app uses three levels at once:

1. SSO entry. The handoff token (issued by parent sso.finance.redirect) authenticates the user into the finance session. No role is checked here.
2. Org membership. EnsureOrgMembership confirms the user is a member of the active organization (or they are switched to a valid one). This reads the finance organizations, users, organization_user tables — separate from the parent's user_organizations.
3. Permission gate. Each route applies perm:<key> or role:<role> middleware. The perm: middleware reads FinanceRolePermissionSet keyed off the user's finance_role_key column. The role: middleware reads Spatie roles.

Common mismatch: the user is in user_organizations on the parent but the finance tenant DB has no organization_user row. They reach finance and get "Organization not found".

Fix. Run the finance superadmin:setup --client-id=<id>, or re-trigger the parent's tenancy projects sync (/admin/clients > Sync Projects).

SSO handoff failures

The flow:

1. Parent: user clicks Launch Solabooks → GET /sso/finance/redirect.
2. Parent issues a short-lived signed token via SsoTokenService.
3. Browser redirects to https://solavel.com/finance/sso/callback?token=….
4. Solabooks: SsoCallbackController calls back to parent POST /api/sso/validate (open route, throttle 60/min) to verify the token.
5. On success, finance opens a session for the user and redirects to /finance/.

Failure modes:

Where to look in logs:

• Parent: storage/logs/laravel.log for Api/SsoValidationController.
• Solabooks: storage/logs/laravel.log for SsoCallbackController.
• Apache: /var/log/apache2/access.log for the redirect chain (the /sso/finance/redirect → /finance/sso/callback?token=… pair should both return 302 then 200).

"I can't see my organization in the picker."

The finance app shows organizations the user is a member of in the top-bar org switcher. If an org doesn't appear:

1. Confirm the user has a row in finance's organization_user table for that org.
2. Confirm the org is is_active = true.
3. Confirm the user's users.organization_id (default org) hasn't been set to a deleted org — that wedges the resolver.
4. Confirm the parent's user_organizations row is in sync.

Fix. From parent /admin/clients > [client] > Sync Users. Then have the user sign out and back in.

Customer portal access dead-ends

Distinct system. See customer-portal/secure-document-links and customer-portal/overview.

API access dead-ends

Related

• support-playbook
• logs-and-errors
• plan-feature-debugging
• reference/permission-matrix