# Organizations and Workspaces

SteelEngine organizes your work in two scopes: **organizations** and **workspaces**. Both have their own URL slugs, and every dashboard URL is built from the pair: `/<orgSlug>/<workspaceSlug>/...`.

## Concepts

**Organization**

The top-level container. Owns billing, members, plan tier, and one or more workspaces. Addressed by an immutable URL slug.

**Workspace**

A project scope inside an org. Holds workflows, chats, knowledge bases, databases and tables, files, and scheduled tasks. Also slug-addressed.

## Personal Organization

SteelEngine accounts are created by invitation (see [Accepting Invitations](#accepting-invitations)). The only exception is the first account of a new install. If you reach the app without belonging to any organization, and the app has no invitation to send you to, SteelEngine creates a personal organization for you and a default workspace inside it. You don't have to choose a name or pick a plan — your first authenticated visit to `/` is enough.

Your personal org is a real organization with the Community plan applied. You can rename it later, invite teammates, and upgrade it to a paid plan — all the same controls that team-created orgs have. The only difference is that the slug was generated for you (e.g. `mild-owl`, `prime-horse`) instead of derived from a name you typed.

You'll know you've landed on it when the URL looks like:

```
https://app.steelengine.com/<your-personal-org-slug>
```

That page is your [organization dashboard](#organization-dashboard) — you enter a workspace from there.

You can belong to additional organizations by invitation. Each organization keeps its own billing, members, workspaces, credentials, and access-control settings.

## Organization Dashboard

Signing in lands you on the organization dashboard at `/<orgSlug>`. It lists the workspaces your effective roles allow you to read and is the home for organization-level management.

When choosing a dashboard after sign-in, SteelEngine checks organization memberships from oldest to newest and opens the first organization you can read. If you still have memberships but none grants read access, it shows a no-access page. It does not create a new personal organization to bypass that restriction.

Organization settings are permission-aware. A section appears when your current role grants its capability:

| Section                     | Representative catalog permission                                                  |
| --------------------------- | ---------------------------------------------------------------------------------- |
| General                     | `organization:read` or `organization:update`                                       |
| Access → People             | Organization or workspace member-management permissions                            |
| Access → Groups             | Access-management permission plus the Access Control entitlement                   |
| Access → Roles and Activity | Full access authority, including `organization:manage_authz` and member management |
| Models                      | `organization:manage_models`                                                       |
| API keys                    | `organization:manage_api_keys`                                                     |
| Workload identities         | `organization:manage_workload_identities`                                          |
| Billing                     | Plan-account billing permissions                                                   |
| SSO and Branding            | Organization settings update permission                                            |

The seeded Admin role initially has full organization authority. Supervisor and Member are useful defaults, but custom roles and edited seeded roles can expose a different set of sections. Workspace visibility likewise follows current catalog grants rather than the role's name.

## Deployment Applications

On a configured self-hosted installation, **Organization settings → Workload identities** registers approved Entra release applications. For explicit access, add each workspace once, then select actions with checkboxes or additive presets. Workflow-specific grants remain in a separate advanced section and require a workflow ID. You can also configure automatic actions for all current and future active workspaces, with exclusions. A workload is a separate machine principal; it receives no human organization role and cannot manage its own permissions. See [Entra workload identity setup](/self-hosting/entra-workload-identities) for installation trust, dashboard registration and pipeline examples.

## Organization Releases

On an enabled self-hosted installation, open **Organization settings → Organization releases** to configure the shared Git repository, development and target branches, workspace mappings, and the target deployment policy. **Workspace release scope** distinguishes managed workspaces from those following their own Source Control connection. The page separates Git approval, preparation, and the currently deployed organization generation. See [Git Approval and Release Status](/self-hosting/releases/git-promotion) for setup.

Changing the repository or upstream branches requires `organization:promotion_repository_configure` at organization scope and read access to the managed workspaces. Admins have this permission by default; custom roles can receive it explicitly. Changing the target's deployment policy also checks the relevant promotion permissions.

Restoring organization ownership of an inherited connection also requires promotion management permission for that workspace.

Release review groups planned workflow and folder changes by workspace. On the target, **Earlier releases → Check rollback readiness** reviews restoration of an eligible retained release across the managed workspaces. Restoration creates a new generation while preserving current drafts and local data.

On the target, **Sync now** verifies and prepares the reviewed release. With **Deploy manually**, the current generation stays live until you select **Deploy organization**. With **Deploy automatically**, a validated release activates after synchronization. Changes that require acceptance pause in either mode.

## Model Restrictions

**Organization Settings → Models** controls which AI models the organization can use. The **Model availability** list groups every model by provider. Turn a model off and click **Save changes** to disable it in every workspace of the organization. Managing the list requires `organization:manage_models`. The list also includes &#x2A;*Laya (Laya Decision block)** where Laya is available; turning it off hides the [Laya Decision](/blocks/laya) block and stops existing Laya blocks from running.

Workspaces can narrow the list further. Open workspace **Settings → BYOK** and find **Workspace model overrides**. It shows each model as **Enabled**, **Disabled**, or **Disabled by org**. Org-disabled models are locked there. A workspace cannot re-enable them.

SteelEngine enforces restrictions when a model is called, not only in the model picker. A run that names a disabled model fails with a model-not-allowed error. On Enterprise plans the same **Models** section also holds organization-level BYOK keys.

## URL Anatomy

Every dashboard URL is composed of two slug segments after the host:

```
https://app.steelengine.com/<orgSlug>/<workspaceSlug>/...
```

| Segment           | Source                                                                                     | Mutable?                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `<orgSlug>`       | Generated from the organization name on creation, or a curated word-pair for personal orgs | Editable in **Organization Settings → General**, independently of the name (changing the slug breaks old links to that org) |
| `<workspaceSlug>` | A 6-character random slug generated when the workspace is created (e.g. `yxc35g`)          | Immutable — display names live in the workspace `name` field and can be freely renamed without breaking URLs                |

Both slugs are unique within their parent scope:

* **Org slug**: globally unique across the platform
* **Workspace slug**: unique within an organization (so the same `yxc35g` could exist under two different org slugs)

Organization slugs cannot use reserved application routes, including `app` and `app-preview`, or the names of marketing site sections such as `blog` and `industries`.

Changing the slug—directly in **Organization Settings → General**, or by renaming during the [upgrade flow](#upgrading-from-personal-to-team)—invalidates old bookmarks and external links, which return a 404. Avoid changing a production org's slug without coordinating with anyone who has bookmarks.

## Switching Organizations and Workspaces

Click the workspace name at the top of the sidebar, or press `Mod` + `O` (`Cmd` + `O` on macOS, `Ctrl` + `O` on Windows and Linux) on any workspace page, to open the **workspace switcher**. It slides out beside the sidebar and dims the page behind it. Press `Mod` + `O` again, press `Esc`, or click the dimmed page to close it.

The switcher has three parts:

* **Organization column** — Down the left edge. **All** shows every workspace you can open, **Pinned** shows your pinned workspaces, and each organization's icon limits the list to that organization. Every organization you belong to is listed, including ones where you can't open any workspace yet; selecting one of those offers **Browse** to find workspaces you can request. Organizations that share a name show their URL slug, and their icons use different letters. A dot marks the organization you're in.
* **Search** — Filters by workspace or organization name and highlights what matched. The letters don't need to be next to each other: `mkt` finds "Marketing". Type `@` followed by a name to pick an organization to limit the list to.
* **List** — Without a search it shows **Pinned**, then **Recent** (the four workspaces you opened most recently, shown when you can open more than five), then **All workspaces** grouped by organization with yours first. Click an organization's chevron to collapse its group; the switcher remembers this in your browser. When you can open more than 40 workspaces, organizations other than yours start collapsed. Click an organization's name to open its dashboard.

Picking a workspace opens it at `/<orgSlug>/<workspaceSlug>/home`. Picking one under another organization also switches the active organization; settings, plan limits, members, credentials, SSO, and access control always come from the organization in the URL. The page stays dimmed while the new workspace loads. If that fails or takes longer than 8 seconds, the page comes back and a message explains what happened.

| Key                       | Action                                                                      |
| ------------------------- | --------------------------------------------------------------------------- |
| `↑` / `↓`                 | Move through workspaces and organization headings                           |
| `Enter`                   | Open the highlighted workspace, or the highlighted organization's dashboard |
| `←` / `→`                 | Collapse or expand the highlighted organization                             |
| `Mod` + `↑` / `Mod` + `↓` | Move the organization column's selection                                    |
| `Tab` (in the search box) | Switch between **Your workspaces** and **Browse**                           |
| `Shift` + `F10`           | Open the highlighted workspace's actions                                    |
| `Esc`                     | Clear the search, then the organization filter, then close                  |

The switcher opens with the workspace you used before this one highlighted, so `Mod` + `O` then `Enter` takes you back to it.

### Workspace Actions

A workspace's &#x2A;*⋯** button, or a right-click on its row, opens its actions: **Pin** or **Unpin**, **Rename**, **Change color**, **Duplicate**, **Export**, **Leave**, and **Delete**. Right-clicking the workspace button in the sidebar opens the same actions for the workspace you're in. Each action applies to the workspace it was opened from and keeps its usual requirements: renaming, recoloring, exporting, and deleting need workspace administration authority, duplicating needs edit access, and the owner of a workspace can't leave it. After you delete or leave the workspace you're in, SteelEngine opens the workspace you used most recently, or the organization dashboard if you have none left. If deleting, leaving, or creating a workspace fails, its dialog stays open and a message explains the failure.

Pins are the same ones the [organization dashboard](#organization-dashboard) shows, and like them they're stored in your browser. You can pin up to 10 workspaces from the switcher across all your organizations; unpin one to pin another.

### Browse

The **Browse** tab lists workspaces in your organizations that you aren't a member of yet, grouped by organization. Your current organization's list loads when you open the tab; expand another organization to load its list. Click **Request access** to ask that workspace's administrators for access; the row then shows **Requested**. An organization with nothing to request, or whose workspaces you aren't allowed to browse, shows a short note instead. If a list fails to load, click **Try again**.

### Creating Workspaces and Inviting Members

The bottom of the switcher holds:

* **New workspace** — Creates a workspace in the organization you're in. When the list is limited to another organization, the button names the organization the workspace will be created in.
* **Invite members** — Invites people to the workspace you're in. Hidden when your organization has turned off invitations.
* **Plan** — On hosted deployments with billing, your plan's name, with **Upgrade** on the Community plan.

On screens narrower than 900 pixels, the switcher covers the sidebar. Drag it to the left, or tap the dimmed page, to close it. On phones and other screens narrower than 768 pixels, the sidebar itself is hidden until you tap the menu button at the top left of the page; the workspace name is at the top of the sidebar that opens.

The [organization dashboard](#organization-dashboard) at `/<orgSlug>` offers the same navigation — every workspace you can access is listed there.

You can be a member of multiple organizations at once. Accepting an invitation adds that organization to your account instead of replacing your personal organization or forcing you to leave another team.

## Workspace Settings

Workspace **Settings** groups its sections into Account, Tools, Subscription, System, and Enterprise. Sections appear according to your deployment, plan, and permissions:

| Section                                     | What it holds                                                                                                                                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **General**                                 | Your editor preferences: auto-connect on drop, canvas error notifications, snap to grid, canvas controls, telemetry. The theme picker links to the [Themes](/organizations/themes) gallery |
| **Integrations**                            | Integration connections, including GitHub Source Control                                                                                                                                   |
| **Secrets**                                 | Workspace environment variables for use in blocks                                                                                                                                          |
| **Custom Tools**, **Skills**, **MCP Tools** | Tools available to Agent blocks and Chat                                                                                                                                                   |
| **API Keys**                                | Workspace and personal API keys                                                                                                                                                            |
| **MCP Servers**                             | Workflow MCP servers                                                                                                                                                                       |
| **Source Control**                          | The workspace binding for a source-controlled repository                                                                                                                                   |
| **BYOK**                                    | Your own provider API keys and workspace model overrides on hosted and self-hosted deployments. Key changes require workspace BYOK management permission                                   |
| **SteelEngine Mailer**                      | Inbound mailer (hosted deployments)                                                                                                                                                        |
| **Email Polling**                           | Credential sets for polling triggers (when enabled)                                                                                                                                        |
| **Recently Deleted**                        | Restore deleted workflows, folders, knowledge bases, tables, and workspace docs                                                                                                            |
| **Subscription**, **Team**                  | Plan and usage, and the organization's members. Both need a hosted deployment with billing. **Team** also needs an organization plan and member-management authority                       |
| **Access Control**, **Whitelabeling**       | Enterprise sections                                                                                                                                                                        |

Renaming a workspace does not happen in Settings. Open the workspace's actions in the [workspace switcher](#workspace-actions) and choose **Rename**. This needs workspace administration authority.

## Accepting Invitations

An invitation email links to `/invite/<id>`. Sign in with the invited email address. Then click **Accept** or **Decline**.

Accounts are by invitation only. If you don't have an account yet, create it from the invitation link: open the link from the email, then sign up with the address the invitation was sent to, by email or with Google. Opening the link is the proof that you received it, so finish signing up within an hour of opening it, or open it again. Signing up with any other address, with an invitation that expired or was revoked, or without opening the link, is refused. The only exceptions are accounts an administrator creates, accounts your company's SSO provisions, and the first account of a new install. The page explains expired, revoked, and already-used invitations. If the invitation was sent to a different email address, the page asks you to sign in with that account.

Invitations reach you only by email. Accepting a workspace invitation needs its link from the email; the same browser can accept for an hour after opening the link. If you belong to no organization and more than one workspace invitation is waiting, SteelEngine shows a chooser at `/invite/choose` with the inviter's name for each, linking to each invitation page. SteelEngine accepts nothing automatically. You accept or decline each one.

An addressed [credential-set invitation](/triggers#email-polling-groups) can also let a new user create an account. Open its `/credential-account/<token>` link and sign up with the address it was sent to, then return to accept and connect the account. A shared credential invitation link with no email addressee requires an existing SteelEngine account; it cannot authorize sign-up.

## Leaving an Organization

The **Leave Organization** button is at the bottom of workspace **Settings → Team**. It removes your own membership through the same path an administrator uses to remove a member. The same rules apply:

* The **Team** section appears on hosted organization plans for members who hold organization member-management authority (`organization:manage_members`). Other members ask an administrator to remove them.
* The full-authority guardrail still applies. You cannot leave if you are the last member able to manage both roles and members.
* SteelEngine removes every role assignment and group membership you hold in that organization together with the membership.

Nothing requires you to stay in a minimum number of organizations. If you end up in none, your next visit to the dashboard creates a new personal organization and workspace for you.

## Upgrading from Personal to Team

When you upgrade your personal organization to a paid plan, SteelEngine first prompts you to choose an organization name. The auto-generated word-pair slug works for solo use but is awkward to share with a team — the prompt is your chance to pick something readable.

The flow:

1. From **Settings → Subscription**, choose Team or Scale
2. The Organization Name dialog opens with your current name pre-filled
3. As you type, SteelEngine checks slug availability in real time and shows a green check or a red conflict
4. Confirm to rename the org and continue to checkout

Renaming during this flow updates both the display name and the URL slug. If you'd rather keep the original slug — for example, because you've already shared links — leave the field unchanged and click confirm. The slug only changes when you actually edit the name.

## API and Slug Considerations

* **User-facing dashboard URLs** use slugs: `/<orgSlug>/<workspaceSlug>/...`
* **Admin and execution APIs** use UUIDs (e.g. `workspaceId` query parameters in `/api/v1/logs`). The internal IDs are stable across renames, while slugs can change. See [API Reference](/api-reference/getting-started) for details.
* **Webhooks and integrations** stored on a workflow are addressed by the workflow's UUID, not by the workspace slug — they continue to work after a slug rename.

## Email Preferences

Marketing and product emails from SteelEngine include an unsubscribe link to `/unsubscribe`. The **Email Preferences** page offers **Unsubscribe from All Marketing Emails**. You can also unsubscribe from one category at a time: marketing, updates, or notifications. Changes take effect within 48 hours. You cannot unsubscribe from transactional emails such as password resets, account confirmations, and security alerts.

## FAQ

## Common Questions

**What happens if I delete my personal organization?**

You can't. There is no delete action for organizations, personal or otherwise, in the UI or the API. If you upgrade to a paid team org and want to leave the personal one behind, rename it or simply ignore it.

**Can I belong to multiple organizations?**

Yes. Invitations add another organization membership to your account. Use the workspace switcher (Mod+O) to jump between workspaces across orgs; the active org follows the URL, so settings and billing apply to the organization you're viewing.

**Where do I create a workspace or invite members?**

At the bottom of the workspace switcher: open it from the workspace name in the sidebar or with Mod+O, then choose New workspace or Invite members. Your plan and the Upgrade button are there too on hosted deployments with billing.

**Why can't I pin another workspace?**

The workspace switcher pins up to 10 workspaces across all your organizations. Unpin one from its actions menu, then pin the new one. Pins are stored in your browser, so another browser or device starts with its own.

**Can I limit how much a workspace spends?**

Yes. A role with the required plan-account billing permissions can set per-workspace usage limits from Organization Settings → Billing. Each workspace's usage is tracked against its own limit.

**Can I leave an organization?**

From workspace Settings > Team, click Leave Organization. It uses the same removal path as an administrator removing a member. It needs organization member-management authority. SteelEngine refuses it if you are the last member with full access authority. There is no minimum number of organizations. If you end up in none, your next visit creates a new personal organization for you.

**Can I move a workspace from one organization to another?**

Not currently from the UI. Workspaces are created inside an organization and stay there. If you need to consolidate workspaces under a different org, contact support — we can migrate the underlying records, but external integrations bound to the old workspace ID will need to be re-pointed.

**What does my personal-org slug look like?**

A two-word combo like `mild-owl`, `prime-horse`, or `quiet-river`, drawn from a curated word-pair list to avoid offensive or confusing combinations. Slugs are globally unique — if your generated pair is taken, SteelEngine regenerates until it finds a free one.

**Can I rename the workspace slug?**

No. Workspace slugs are 6-character random strings generated at creation time and are immutable. The display name is freely editable: open the workspace's actions in the workspace switcher and choose Rename. The rename only affects what shows in the sidebar and switcher — the URL slug stays stable.

**Why is my workspace slug something cryptic like 'yxc35g'?**

SteelEngine generates short random slugs to keep URLs short, avoid name collisions across workspaces in the same org, and keep the URL stable across renames. If you'd prefer a memorable URL, the org slug (which IS derived from the name) carries that signal — `acme-corp/yxc35g/...` reads as 'Acme Corp's first workspace' once you know the convention.

**Do API keys work across organizations?**

Not across organizations, but an organization key can span selected workspaces or workflows inside one organization. Each key grant has a read, write, or admin transport ceiling, and the key owner must also hold the required PBAC permission. Use a separate key for another organization.

**What if my paid team needs a different name than my personal org?**

Use a separate team organization rather than renaming the personal one. Once you're invited to that team org, the workspace switcher shows its workspaces under their own organization heading so you can move between the personal org and team org without losing either membership.
