Workspaces in ET Ducky

A workspace is your team's tenant on ET Ducky — the outer container that everything else lives inside. One workspace owns one URL (a subdomain on etducky.com like acme.etducky.com) and can hold one or many Clerk organizations. Agents, alerts, scripts, tickets, integrations, and team members all belong to organizations; organizations belong to a workspace.

If you're a single team monitoring your own infrastructure, you'll typically have one workspace with one organization inside it. If you're an MSP managing multiple clients, you'll have one workspace with one organization per client.

Concept	What it is	Examples
Workspace	Your team's tenant. Owns the URL, the seat pool, and the workspace member list.	acme.etducky.com
Organization	An isolation boundary inside the workspace. Owns agents, alerts, scripts, tickets, and integrations.	“Acme Internal”, “Client A”, “Client B”
Subdomain	The DNS hostname that routes to your workspace. The slug is editable; the binding is permanent.	acme in acme.etducky.com

Your Workspace

Every ET Ducky team gets a dedicated workspace at a subdomain on etducky.com. The workspace is created automatically the first time you sign up — you never have to ask, and you can start using the dashboard immediately.

What happens at sign-up

The moment your Clerk account is created, ET Ducky provisions:

• A workspace with a random readable slug like etd-x7q3p2.etducky.com
• A default Clerk organization inside the workspace, with you as its owner
• Owner membership for you on the new workspace

You'll land on your dashboard at the auto-generated URL with everything wired up. No claim wizard, no DNS setup, no waiting.

Signing in for the first time at etducky.com

If you sign in at the apex URL (etducky.com) rather than a workspace subdomain, ET Ducky checks how many workspaces you belong to and routes you accordingly:

• Zero workspaces — the Claim your subdomain modal opens. Pick a slug, click claim, and we provision your workspace and a default organization, then redirect you to <slug>.etducky.com.
• One workspace — you're redirected straight to it.
• Two or more workspaces — the Choose your workspace picker opens with one row per workspace and your role in each, so you can decide which one to enter.

Personalizing your URL

Default slugs are fine for getting started, but most teams want something memorable. To rename your workspace, go to Settings → Workspace in the dashboard. Renaming is instant and preserves every existing org binding, agent, alert rule, integration, and ticket — only the URL changes.

After a rename, the old subdomain continues to work as a grace-period alias for a window so any in-flight bookmarks, invite links, and agent connections keep functioning while your team migrates. Agents pick up the new URL automatically through their existing SSE connection — you don't need to reinstall or reconfigure them.

What you do NOT need to do

• No DNS changes on your end. The subdomain resolves automatically. Nothing to configure with your domain registrar.
• No certificate request. The HTTPS cert covering *.etducky.com is already provisioned. Your URL is TLS-secured immediately.
• No firewall rule. Your team accesses the dashboard from anywhere — nothing changes on your network.

Slug rules (when renaming)

• 3–63 characters, lowercase letters, digits, and hyphens only
• Cannot start or end with a hyphen
• Cannot match reserved names (www, admin, api, status, mail, etc.)
• Slug is unique across ET Ducky — if your preferred slug is taken, the rename will reject it and you can try another

Picking a good slug

Use your company name or a recognisable abbreviation. The slug appears in URLs your team and end-users will see, and it's part of your invite links. Short, memorable slugs are best. URLs you've already shared (invite links, agent installer URLs, integrations) will need to be reissued after a rename, since the host portion changes.

Inviting Team Members

Once your subdomain exists, your invite links route to it automatically:

https://acme.etducky.com/join?token=<invite-token>

Send the link to a colleague, they sign in with Clerk, and they're added to your subdomain with the role you specified. Invite links expire after 14 days by default, with optional shorter expirations for sensitive roles.

Custom Domains (Optional)

If you'd rather access ET Ducky at a domain you already own — for example app.acme.com instead of acme.etducky.com — you can map a custom domain. This is purely cosmetic; both URLs reach the same data and the same tenant.

Step 1: Pick a subdomain on your own domain

Use a subdomain like app.acme.com or etducky.acme.com, not the apex acme.com. Apex CNAME records aren't allowed by DNS spec on most providers. If you really want the apex, ask your DNS provider whether they support ALIAS or ANAME records.

Step 2: Add a CNAME in your DNS

In your DNS provider's dashboard, add this record:

Type	Name	Target
CNAME	app	acme.etducky.com

If your domain is on Cloudflare: set this CNAME to DNS only (gray cloud), not Proxied (orange cloud). Proxied CNAMEs cause certificate issuance to fail because Cloudflare will redirect ACME challenges to HTTPS before the cert exists.

Step 3: Verify ownership

In ET Ducky, navigate to Settings → Custom Domains and click Add Domain. ET Ducky will give you a TXT record to add to your DNS. Add it in the same DNS provider:

Type	Name	Value
TXT	_etducky-verify.app	etducky-verify=<token>

Wait 5 minutes for DNS to propagate, then click Verify.

Step 4: We issue your certificate automatically

As soon as verification succeeds, ET Ducky queues a TLS certificate request from Let's Encrypt. You don't have to do anything — the cert is issued, nginx is reconfigured, and your custom domain goes live, usually within a few minutes. You'll get an email confirmation when it's ready.

Maintenance

• Renewals are automatic. Let's Encrypt certs are valid for 90 days; ET Ducky renews them well before expiry.
• If you remove the CNAME later, the cert renewal will fail and you'll get a notification. Either restore the CNAME or remove the custom domain from your settings.
• Multiple custom domains per tenant are supported. Useful if you're rebranding or operating under multiple brand names.

Single Sign-On (SSO)

Once you've verified a domain, you can route signins from that domain through your existing identity provider. ET Ducky supports SSO via Clerk's enterprise authentication, with a one-click setup for Microsoft 365 / Microsoft Entra. Traditional SAML for Okta, OneLogin, JumpCloud, and other custom IdPs is on the roadmap.

What "Enable Microsoft SSO" does

When you toggle Enable Microsoft SSO on a verified domain, three things happen:

• The domain is added to ET Ducky's Clerk enterprise SSO connection.
• Future signins from @yourdomain.com email addresses are auto-routed to Microsoft instead of asking for a password — your IT keeps controlling who has access via Entra ID.
• The first user from your tenant to sign in triggers a one-time admin-consent prompt in your Microsoft tenant ("Allow ET Ducky to read user profile and email"). Once your tenant admin clicks Allow, subsequent users sign in transparently.

Prerequisites

• The domain must be verified (TXT record + Check verification) before SSO can be enabled. Verification establishes that you control the domain before you wire it to your IdP.
• You must have a Microsoft Entra ID tenant attached to your Microsoft 365 / Azure account. Personal Microsoft accounts (@outlook.com, @hotmail.com) don't have a tenant and can't be used as the SSO authority.
• Your Microsoft tenant admin needs Global Administrator or Application Administrator role to consent to the app the first time it's used.

Enabling SSO

1. Verify your domain first (see Custom Domains section above).
2. Go to Settings → Verified Domains.
3. Click Enable Microsoft SSO on the row for your verified domain.
4. Read the confirmation prompt and click OK.
5. The row now shows an "SSO: Microsoft" badge. Future @yourdomain.com signins are routed through Microsoft.

What happens on first signin from a domain with SSO enabled

The first employee from your domain signs in, is redirected to Microsoft's signin page, and authenticates against your Microsoft tenant using your password rules, MFA, and conditional-access policies. If they're the first user from your tenant to reach ET Ducky, Microsoft shows an admin-consent screen ("ET Ducky wants to read user profile, email"). The signing-in user clicks Allow if they have the right role, or forwards the screen to their IT admin. Once consent is granted, all subsequent @yourdomain.com users sign in transparently.

Users from other email domains in your workspace (for example a @gmail.com external contractor) continue to sign in normally with their existing method. SSO only applies to the domains where you've explicitly enabled it.

How user isolation works

ET Ducky uses a single multi-tenant Microsoft app under the hood, but each customer's users authenticate against their own Microsoft tenant — never against ET Ducky's tenant. If your IT disables an employee in Microsoft Entra, their ET Ducky access stops on their next signin. ET Ducky doesn't store passwords for SSO users; Microsoft does. Different ET Ducky customers using SSO are completely isolated from each other — the shared Microsoft app is only an authentication intermediary, never a data path.

Disabling SSO

Toggle Disable SSO on the verified domain row. Future signins fall back to whatever auth method they had before (password, Google, etc.). Sessions that were already signed in via SSO stay valid until they expire naturally (typically within a week); to force immediate re-authentication, contact support.

Custom SAML providers

If your IdP isn't Microsoft 365 / Entra ID (Okta, OneLogin, JumpCloud, or a custom SAML provider), the Microsoft-EASIE one-click flow won't fit. Custom SAML support is on the roadmap and will surface as an "Advanced: Configure SAML manually" option on the same verified-domain row. Contact support if you need this today; we can configure the Clerk-side connection manually while the self-serve UI is in development.

Pending Join Requests

When someone signs up with an email at a non-public domain that's already claimed by another ET Ducky workspace, ET Ducky doesn't create a parallel workspace for them. Instead, it surfaces a Pending join request banner at the top of their dashboard pointing at the existing workspace, with options to Withdraw request or Hide for now. The original workspace owner sees the request on their Team page and can approve or reject it.

• Approved: the user is added as a workspace member with the default role (member). They can switch to that workspace from their org picker.
• Rejected or withdrawn: the user stays on their personal auto-bootstrapped workspace.
• Expired: requests expire after 30 days if no decision is made.

If SSO is enabled for the email's domain on the claimant's workspace, the request is skipped entirely — Clerk's SSO flow handles membership automatically during signin and no manual approval is needed.

Free-email signups (gmail.com, outlook.com, proton.me, etc.) always get a fresh personal workspace; they never trigger a join request because there's no notion of a "company workspace" for a free-email domain.

Multiple Organizations in One Workspace

If your team is an MSP managing multiple client organizations, all of those orgs live in your single workspace. The dashboard's organization picker (top-left) lets you switch between them; the URL stays the same (acme.etducky.com), but the API requests carry an X-Clerk-Org-Id header that scopes everything to whichever org you've selected.

A single login at acme.etducky.com gives you access to every organization in the workspace — no logging out and back in.

Workspace membership cascades to every org

When someone is added to your workspace — through a workspace invite, by accepting an invite at the workspace URL, or by you binding an existing organization to the workspace — ET Ducky automatically grants them membership in every Clerk organization that already lives in the workspace. New organizations created later in the workspace also receive every existing workspace member as a member of that new org. The result is that “workspace member” and “has access to all orgs in the workspace” are the same thing in practice; you don't have to invite people to each org individually.

If you need someone to see only a specific organization (for example, a customer's IT contact who should see their fleet but not your other clients'), invite them directly to that organization at its own subdomain rather than to your workspace. Workspace-level invites are the right tool for your own team and partners; per-org invites are the right tool for client-facing access.

Org dropdowns only show this workspace

Every organization picker in the dashboard — on the Dashboard, Agents, Team, Alerts, Reports, Tickets, Integrations, Automations, and KB pages — lists only the organizations that belong to the current workspace. If you're a member of multiple workspaces, you won't accidentally see an org from a different workspace in the dropdown, and switching orgs can never load data from outside the workspace you're in. The list is sourced from the API directly (rather than from your browser's Clerk session), so it stays consistent no matter which workspace you switched from last.

How data is partitioned between orgs

Each Clerk organization inside the workspace is its own isolated tenant. Switching the active org in the picker re-scopes every page in the dashboard:

• Agents are scoped per Clerk org. The Agents page only shows agents installed under the currently-active org. Switching orgs gives you a different fleet view.
• Alert rules, automations, scripts, tickets, and integrations are all per-org. A script you create under Acme Org A is invisible from Acme Org B, even though both are in the same workspace.
• Live sessions and remote desktop can only target agents in the active org. To remote into a machine in a different client's fleet, switch to that client's org first.
• Subscriptions and billing roll up at the workspace level (your team's owner pays for all seats across all client orgs); usage attribution per client org is visible on the Billing page.

This architecture deliberately keeps client data separated. If you'd rather have one shared fleet across multiple internal teams, put them all in a single Clerk org under the workspace rather than separate orgs.

Active org auto-selection

If only one Clerk org exists in the workspace, it's selected automatically on every login. If several do, the dashboard remembers the org you last used in this workspace. Need to switch on every visit? Pick from the org picker each time — selection persists per browser tab.

Troubleshooting

"Workspace not found" / "Subdomain not found"

Double-check the slug spelling. If you just registered, give DNS a couple of minutes to propagate. If you registered a long time ago and the workspace was deactivated for inactivity, contact support — deactivated workspaces can be reactivated for up to 90 days after deactivation.

"Active organization is required"

You're hitting a workspace URL but Clerk hasn't set an active organization. Click the org picker in the top-left and select one. If only one organization exists in the workspace, this is set automatically; if you've just been removed from your last org in the workspace, contact your workspace owner. The dashboard auto-recovers from a stale active org by intersecting your Clerk memberships with the current workspace's org list and selecting a valid one.

"You don't belong to any organization in this workspace"

You signed in at a workspace URL where you're a workspace member but have no current Clerk org membership inside it — usually because every org in the workspace was created before you joined, or because all of your org memberships in this workspace were removed. The membership cascade fixes this automatically when new orgs are created or when you're re-invited; in the interim, ask a workspace admin to add you to one of the existing organizations or to re-invite you.

Custom domain verification fails

Most common cause: DNS hasn't propagated yet. Run dig +short TXT _etducky-verify.app.acme.com from your terminal — the TXT value should match what ET Ducky asked for. If it returns nothing, your DNS update hasn't taken effect; wait or check that you saved the change in your DNS dashboard.

Second most common cause: your domain is on Cloudflare with the proxy enabled (orange cloud). Cloudflare doesn't expose TXT records the same way to external lookups. Set the verification CNAME and TXT to DNS-only (gray cloud) until verification succeeds; you can re-enable proxy afterwards if you want.

Custom domain TLS shows a "your connection is not private" error

Check that you're hitting the URL exactly as configured (no typos in the subdomain). If the domain was just verified, the certificate may still be issuing — wait 5 minutes and refresh. If the error persists, the cert issuance probably hit a rate limit or DNS failure; contact support and we'll re-trigger it.