User-Tenant Onboarding and Membership

Overview

The User-Tenant design covers self-serve multi-tenant onboarding and membership management. Users can self-sign-up, self-subscribe, and self-manage their tenant memberships.

Key Entities (ERD)

Sign-Up Flow

1. User registers in Cognito (email + password).
2. A PostConfirmation Lambda creates UserAccount, personal Tenant, and AgentFor linking the user to their personal tenant.
3. The personal tenant provides freemium access and cannot be deleted.
4. The frontend receives a JWT containing oidc:sub.

HubSpot Sign-Up Flow

1. User pays in HubSpot.
2. HubSpot triggers a webhook to the BFF.
3. BFF creates the user in Cognito via AdminCreateUser, then calls Accounts to create UserAccount, personal tenant, AgentFor.
4. Accounts also creates a paid tenant and a second AgentFor. The paid tenant becomes the default agent.
5. BFF updates the Cognito user record with custom:tenant = paid.tenant.id.

Sign-In Flow

1. User authenticates in Cognito and receives a JWT.
2. Frontend queries the Account service using oidc:sub to get user account details and list of AgentFor records.
3. The UI shows the current tenant and a mechanism to switch tenants. The choice is persisted for future sessions.
4. All subsequent requests include the JWT and X-TENANT-ID header.

Invite Flow

1. Tenant admin generates an invitation URL via the Invitations service.
2. The invitation stores invitee.email, tenant.id, inviter.id, and expiresAt.
3. The invitee opens the URL, signs in or creates an account.
4. On acceptance, a new AgentFor is created and the invitation is marked accepted. On decline, it is marked declined.

Evict Flow

The tenant admin selects a user, confirms eviction, and the system deletes the AgentFor. Subsequent requests from that user with the same tenant will receive a 403.

Create Paid Tenant Flow

A user creates a paid tenant from their personal tenant. They become the tenant admin of the new tenant. A new AgentFor is created linking the user to the new tenant.

Request Authentication

All requests carry:

• JWT (from Cognito) identifying the user
• X-TENANT-ID header identifying the active tenant

The backend re-validates the X-TENANT-ID against the authenticated user’s memberships on every request to prevent horizontal privilege escalation.