Onboarding a Workspace

Runs unlicensed

Available with no license, in the Development posture. A license adds the MCP and A2A planes, production rights and support — not this feature.

This is the end-to-end flow for bringing a new workspace online. It starts with a platform owner and ends with a freshly-minted workspace admin who can manage the workspace from the portal on their own. All of it happens inside the Flightdeck — no shell access, no database edits.

This guide assumes built-in email/password authentication (the default). The OIDC and SAML modes are slightly different and covered at the end.

Quick map

owner creates the workspace → owner invites the workspace admin → admin clicks email link → /register → logs in → lands at /portal → invites the rest of their team.

Prerequisites

• A platform owner account signed in to the Flightdeck. If this is your first time, run through First-run setup to create the initial owner.
• The six built-in roles and their capabilities are documented in Setup & Login → RBAC roles. This guide uses owner (platform) and admin (workspace).
• For production, email delivery needs to be configured — see Email delivery below.

Step 1 — Create the workspace

In the sidebar, open Identity → Workspaces and click New Workspace. Fill in the basics (name, region, priority tier) and submit.

Figure 1. Create-workspace form

When the save succeeds, a toast appears at the top-right with a call-to-action link:

✅ Workspace 'Acme Corp' created. Invite admin →

The toast stays up for seven seconds. Click Invite admin → while it's still visible and you'll be dropped on the invite form with the right context already filled in. If you miss it, the same deep link is available from the workspace's edit page (next step).

A WORKSPACE_CREATED event lands in the audit log at this point; see it under Audit → Events.

Step 2 — Review the Team section (optional)

Open any existing workspace's edit page (Workspaces → Edit on the row). A new Team section in the sidebar lists users assigned to this workspace plus two deep-link buttons:

• Invite admin — pre-selects the workspace role admin
• Invite with other role… — opens the invite form with just the workspace ID pre-filled so you can pick developer or viewer manually

Figure 2. Workspace edit form — the Team section is in the left sidebar

Each row shows the user's email (linked to their edit page), name, roles, and status (INVITED / ACTIVE / SUSPENDED). An INVITED user hasn't set their password yet — they're waiting to click the email link.

Step 3 — Send the invitation

Whichever path you took, you land on /users/new with the workspace ID and role already populated.

Figure 3. Invite user form with role checkboxes

Fill in:

• Email — where the invitation will be sent.
• Name — optional display name.
• Roles — leave admin checked. You can assign multiple workspace roles but you cannot mix platform and workspace roles on one user.

Click Send Invitation. The server:

1. Creates a User record with status=INVITED and a 7-day verification token.
2. Renders the invitation email from a template and hands it to the configured transport (log or SMTP — see below).

Step 4 — Workspace admin accepts the invitation

The invitee receives an email with a Set your password link that points at /register?token=<uuid>. The token is single-use and expires in 7 days. When they open it:

1. They're asked for a password (minimum length is enforced — see built-in auth config).
2. On submit, the User flips from INVITED to ACTIVE, the token is cleared, and they're redirected to /login?registered=true.
3. They log in with their email and the password they just set.

Because their role is admin (a workspace role), the login flow drops them at /portal, not /.

Step 5 — Hand off to the workspace admin

At /portal the new admin sees the workspace-scoped dashboard — usage, cost, audit, API keys, provider credentials, and a Team page. From Team → Invite, they can invite their developers and viewers without involving the platform owner.

Figure 4. What the customer sees at /portal after the invitation flow completes — KPI tiles, quick actions, and a Team link in the sidebar. No platform-owner concepts (routes, policies-as-platform, billing console) are visible; the page is scoped to the admin's own workspace.

Scope limits the admin to their own workspace: they can only invite users whose role is admin, developer, or viewer, and every invitation they send is scoped to their workspace automatically.

From this point the platform owner is out of the loop unless they need to change role assignments, suspend the workspace, or manage platform-level resources.

Email delivery

The invitation email is built from a templated HTML body and delivered by one of three transports, configured with dvara.flightdeck.email.transport (env: DVARA_FLIGHTDECK_EMAIL_TRANSPORT):

• log (default, for local and CI) — the entire email including the /register?token=… link is printed to the Flightdeck logs at INFO. Grep the log by the recipient address to find the token.
• smtp (production) — uses the standard SMTP properties (spring.mail.host, spring.mail.port, spring.mail.username, spring.mail.password). Set dvara.flightdeck.security.builtin.base-url to the public Flightdeck URL — otherwise the link the user receives will point at http://localhost:8090/register?token=…, which is exactly the kind of detail you discover only after a real user tries to click it.
• resend (production) — POSTs to the Resend transactional API. Set dvara.flightdeck.email.resend-api-key (re_…) and verify your sender domain in Resend, or use the sandbox sender onboarding@resend.dev for testing. Same base-url requirement as smtp for the link's host.

Token lifetime is seven days. Expired tokens render as invitation link is invalid or has expired on /register; there's no self-service resend yet, so the invite needs to be re-sent from /users/new.

Audit events

Onboarding shows up in the immutable audit trail as:

Event type	Emitted when	Payload highlights
WORKSPACE_CREATED	A platform owner creates the workspace in step 1	workspace_id, name, status, metadata, actor
WORKSPACE_METADATA_UPDATED	Any subsequent edits to the workspace	workspace_id, actor, changes (diff per key)
WORKSPACE_DELETED	The workspace is deleted	workspace_id, name, status, actor
USER_INVITED	Step 3 succeeds — user persisted with status=INVITED and the invitation email delivered	user_id, email, workspace_id (null for platform-role invites), roles, status (INVITED), actor

Token acceptance at /register (step 4) does not currently emit its own audit event. If you need richer audit coverage of user lifecycle, creating users in the Console emits USER_CREATED, USER_INVITED and USER_ROLE_ASSIGNED, which is the richer trail.

OIDC and SAML deployments

If the Flightdeck is configured for OIDC (Enabling OIDC) or SAML, identity is owned by your IdP, not by DVARA, and this flow is slightly different:

• OIDC — users are not sent an invitation email. They exist in DVARA either by being created ahead of time via the Users page (invite-first mode) or by being auto-provisioned on first login from the JWT claims. /register is not used.
• SAML — same shape as OIDC. With dvara.flightdeck.security.saml.auto-provision=true, the user is created on first successful assertion using defaultRoles and defaultTenantId. For scripting against the Flightdeck, issue a personal access token (dvara_pat_…) — note the Admin API it used to target was removed in 1.7.0.

In both modes, the Team section on the workspace edit page and the portal team page still work for role assignments; only the email + password flow is skipped.

Troubleshooting

The CTA toast disappeared before I could click it. It stays up for seven seconds. If you missed it, open the workspace's edit page — the Team section has the same deep-link buttons.

The invitee clicked the link and got invitation link is invalid or has expired. Either the 7-day TTL has passed or the invite has already been consumed. Re-send from /users/new.

The invite email never arrived. Check the email transport. In log mode, the email is in the Flightdeck logs — grep for the recipient address. In smtp mode, verify dvara.flightdeck.email.from and the SMTP connection properties, and confirm the SMTP host is reachable from the Flightdeck pod.

The admin logged in but landed on / instead of /portal. That means they ended up with a platform role (owner, policy-admin, billing-admin) instead of a workspace role. Edit the user and check the role assignments — mixing platform and workspace roles on one user is rejected at create time, but a role mistakenly set to owner will land the user on the platform dashboard.