logicspike/docs

Authentication & Team

User Journey: Tenancy & Team Management

This document outlines the product and user-experience flows for identity, multi-tenant workspace switching, and team lifecycle management in LogicSpike.

1. The "Building & Floors" Mental Model

Users authenticate into the Lobby (Global Identity). The credentials they use (Email/Password, Google, Phone) belong to them personally. However, the Tokens they receive are Keys to specific Floors (Tenants). A user can be a member of multiple Tenants, holding different Roles (and therefore different PBAC permissions) in each.

2. Multi-Tenant Navigation & Switching

The Lobby (Workspace Selection)

When a user logs in, if they belong to multiple active workspaces, they land in a generic selector screen:

  • 🏢 TechStartup (Owner) [Last Active]
  • 📝 ClientProject (Editor)
  • 🎨 Hobbies (Owner)

Selecting a workspace securely issues or provisions the context for that specific tenant_id.

Switching Context (The "Instagram" Feel)

Once inside the seller dashboard:

  1. The user clicks their workspace name in the top sidebar.
  2. A dropdown lists their other workspaces.
  3. Upon selecting a different workspace, the page refreshes dynamically.
  4. The system issues a new JWT or switches context entirely. If they are an Owner in Workspace A but only an Editor in Workspace B, UI elements like "Settings" will hide or lock instantly upon switching.

Creating a New Tenant

Users can create a new workspace independently of their registration.

  • Action: Creating a new workspace generates a new tenant record.
  • Role: The user is automatically assigned the role_owner membership.
  • Context: The Dashboard immediately switches context to the new workspace.

3. Team Management Lifecycle

A. The Delegation (Custom Roles & PBAC)

An Owner (e.g., Ayva) can delegate specific powers without giving away full control.

  1. Ayva creates a new Role called "HR Admin".
  2. She assigns specific PBAC permissions like team:manage (invite/remove members) but intentionally omits billing:manage.
  3. She assigns this role to a staff member (Ben). Ben's dashboard updates to suddenly show the "Invite Member" button.

B. The Invitation (Hiring Staff)

  1. Ben (with team:manage permission) enters an email (e.g., chloe@dev.com) and selects a Role.
  2. The system generates a time-limited magic link and creates a pending invitations record.
  3. Chloe receives an email. Upon clicking the link:
    • If she is new: She is prompted to register (Email/Password or Google). Upon completion, her new User record is immediately linked via memberships to the workspace.
    • If she exists: She is prompted to log in. The existing user is linked to the workspace.

C. Live Permission Updates (Promotion)

If an Owner promotes a user (e.g., Developer -> Lead Developer) via the Settings panel, the API updates the memberships table immediately.

  • Constraint: Because permissions are embedded in the JWT token for zero-latency checks, changing a role requires forcing the user's client to refresh its session token. A real-time prompt or polling system must tell the active user: "Your permissions have changed. Refreshing session."

D. Offboarding & Removal

When a user is removed from a workspace:

  1. The memberships record is deleted or marked revoked.
  2. Asset Transfer: An option is presented to either delete or transfer ownership of assets (like API keys or Blog Posts) created by the departing user.
  3. Session Revocation: The system immediately invalidates the user's active session for that specific tenant. The user can still log into LogicSpike for their other workspaces, but the removed workspace immediately disappears from their UI.
Authentication & Team