Operating the registration module

You're the operator. You want to open this ScaiControl deployment to new customers, either as a public sign-up, by invitation only, or via a waitlist with manual approval. This tutorial walks through each path, plus the day-to-day operations (issuing, revoking, switching modes) you'll do once you're live.

Prerequisites:

• A super_admin account on this deployment.
• The browser open at /admin/registration.
• A rough idea of which partner the new tenants should attach to (the default partner ID — set once in the Settings tab).

If you're new to the model first, read Registration modes.

1. First-time setup#

The Settings tab is the only screen that matters for setup. Open Admin → Registration → Settings:

1. Mode — start with disabled (the safe default). You'll flip this in step 4.
2. Default partner ID — paste the UUID of the partner that new self-serve / waitlist sign-ups should attach to. (Invitations can override this per-invitation.)
3. Default trial pack slug — optional, but recommended. If you have a "trial-bundle" service pack, set its slug here and every new tenant is auto-subscribed on creation.
4. Email-domain allow / block lists — optional. Set allowed_email_domains if you want to lock the deployment to a specific organisation (e.g. acme.com).
5. Save changes.

You're set up — the deployment is in disabled mode and refuses every public registration path. Time to pick a real mode.

2. Enable invitation mode (closed beta)#

The most common starting point. You manually decide who gets in.

In Settings, change mode to invitation and save. The Settings tab will ask you to confirm: "The public sign-up / waitlist form will stop accepting new requests; only admin-issued invitations will create new tenants." Click Switch mode.

Now issue your first invitation:

1. Open the Invitations tab.
2. Click + Issue Invitation.
3. Fill in:
   • Email: alice@acme.com
   • Partner ID: pre-fills from your default; override if this tenant attaches to a different partner.
   • Company name (optional, for display).
   • TTL hours (optional, defaults to 336 = 14 days).
4. Click Issue & email.

The modal closes and a green banner appears:

Invitation issued — copy the accept URL if needed https://scaicontrol.scailabs.ai/auth/accept-invitation?token=...

In v1, you paste this URL into your own email client (whatever you use to talk to prospects). The token is the only secret part — once the recipient clicks it, ScaiControl handles the rest. The raw token is shown to you once and is never stored unhashed.

When the recipient accepts:

• Their tenant + tenant_admin user are created.
• The invitation row flips to accepted.
• ScaiKey emails them a "Welcome — set your password" link.
• registration.completed.v1 fires (your CRM picks it up).

3. Enable waitlist mode (capacity-constrained launches)#

You expect more interest than you can handle. Open the gates partially: the public form collects everyone, you decide who comes in.

In Settings:

• Change mode to waitlist.
• Configure waitlist capture fields — defaults to ["company_name", "use_case"]; add anything else you want the form to ask for. The public form renders an input per slug.
• Save.

The public form is now live at <portal>/auth/join-waitlist. Visitors fill in their email + your configured extras and queue up.

To process the queue:

1. Open the Waitlist tab. Pending entries are sorted oldest-first.
2. For each entry you want in:
   • Click Approve.
   • Optionally override the trial pack or the invitation TTL.
   • Click Approve & issue invitation.
3. A green banner appears with the accept URL — paste it into your email client to the prospect.

The entry's status flips to approved, the invitation appears in the Invitations tab, and the recipient lands on the same accept page as a directly-issued invitation. From their perspective it's identical.

To reject:

• Click Reject, optionally include a reason (logged for your records, not emailed to the user).

Duplicates are auto-detected — if someone tries to join the waitlist with an email that's already a user or has a pending invitation, the entry lands with status duplicate and you'll see a ghost badge. No event is emitted for duplicates; admin churn stays low.

4. Enable self-serve mode (public launch)#

You're ready for the world. Anyone with an email passing your domain policy can sign up themselves.

In Settings:

• Change mode to self_serve.
• Crucially: re-check your email-domain allow / block lists. Without them, anyone with any email can create a tenant.
• Save and confirm.

The Settings tab will warn you: "Self-serve sign-up will be open to the public. Make sure the email-domain allow/block lists are set the way you want them."

The portal login page now shows a NEW HERE? — Create a tenant CTA. The public sign-up form lives at <portal>/auth/sign-up.

5. Day-to-day operations#

Resend an invitation#

If a prospect lost the email, open Invitations, find their row, and click Resend. Same token, no state change — useful when their inbox ate the first one.

If you want the old link to stop working too (e.g. you suspect it was forwarded), click Rotate instead. A fresh raw token is minted, the old token's hash is overwritten, and the previous link returns "invitation invalid" on click.

Revoke an invitation#

For a prospect you've decided not to onboard after all:

• Open Invitations, find the row, click Revoke.
• The link stops working immediately.
• invitation.revoked.v1 fires.

You can only revoke pending invitations. Already-accepted invitations live on as the resulting tenant — disable the tenant from Admin → Tenants if you need to undo onboarding.

Switch modes safely#

Every mode switch shows you a preview of what's being stranded:

Switching to invitation will leave 17 pending waitlist entries unaddressed. The public sign-up / waitlist form will stop accepting new requests; only admin-issued invitations will create new tenants.

Click Cancel to back out, or Switch mode to proceed. Pending records aren't touched by the switch — they stay in their queue, you can still approve them manually, you just stop receiving new ones until you switch back.

A typical operator arc:

1
2
3
4
5

launch day → invitation (manual, controlled)
   ↓ (after a week of soak)
soft-launch → waitlist (collect demand)
   ↓ (capacity confirmed)
GA → self_serve (open the gates)

You can move back at any time. Moving from self_serve → disabled is the emergency-stop pattern: existing users keep logging in, but no new tenants can register.

6. Watching the work queue#

The Dashboard (for super_admins) shows a Registration widget at the top:

1
2
3
4

Registration                              [ invitation ]
Pending invitations: 3 (oldest 2d)
Waitlist (pending):  0
Last 7d activity:    1 accepted · 0 approved

If a number looks wrong — invitations stacking up because nobody's accepting, waitlist growing faster than you're approving — it's the cue to dig in. Click Open registration admin → to jump straight to the tabs.

7. Common pitfalls#

Next#

• Registration modes — the underlying model.
• Webhooks — wire the registration + invitation + waitlist topics to ScaiCRM.
• Service packs — what default_trial_pack_slug actually activates.