Billing and identity architecture for a live, paying client's multi tenant SaaS platform.
Search Sensei wraps an existing enterprise search API in a multi tenant customer portal. Organisations self register, choose a subscription plan, and get an isolated workspace with authentication, billing, a knowledge base, and support ticketing. There is zero cross tenant visibility between organisations.
Onboarding dropped from manual provisioning to under five minutes once the portal shipped.
Browser authenticates via Auth Code + PKCE with Keycloak, then sends Bearer JWT to the backend. The backend is the only component that talks to the outside world. It proxies every downstream call, attaching the right credential per service. The browser never sees the BookStack PAT, the Zammad PAT, or the Stripe secret key.
Three consumption dimensions tracked through Stripe: search query volume, document pages indexed, and additional sites crawled. An internal endpoint accepts usage events and requires a caller supplied idempotency key. It forwards each event to Stripe as a meter event only once, preventing double counting on retries. Subscription and customer IDs are stored as attributes on the Keycloak organisation itself, not duplicated into a first party database. This gives a single source of truth for which org maps to which Stripe customer.
The system uses Keycloak 26 native Organisations to scope users, roles, and sessions to an org boundary, instead of building tenant isolation into application code. The backend resolves the current tenant from an active_tenant claim on every request. Isolation lives in a battle tested layer rather than bespoke logic.
BookStack and Zammad both require long lived Personal Access Tokens. Every call passes through the ASP.NET Core backend. The backend holds the PAT and returns only what the authenticated user is allowed to see. No dedicated API gateway is needed. The backend itself is the trust boundary.
| Service | Role | Auth method |
|---|---|---|
| Keycloak 26 | Identity, multi tenant org management, SSO broker | Client Secret + PKCE |
| Stripe | Checkout, subscriptions, metered billing | Secret Key + Webhook Signature |
| BookStack | Knowledge base via backend proxy | PAT via backend proxy |
| Zammad | Support ticketing via backend proxy | API Token via backend proxy |