Organizations

An organization is a tenant that groups workspaces and people under one management surface — the org portal at /org/<slug>/.... Organizations are how a company manages many workspaces centrally: one owner team, shared skills and agents, one SSO configuration, and shared credit, while each workspace keeps its own members, content, and settings.

What you get

The portal is owner-only. A member whose org role is billing sees only the Billing page; platform admins (User.is_admin) bypass org-level checks, as they do everywhere else.

Org roles and RBAC

Organization memberships carry one of three roles (OrganizationMembership.org_role):

• owner — full org portal access; can manage members, workspaces, SSO, org skills, org agents, and API clients.
• member — regular membership; no org portal access.
• billing — access limited to the Billing page (wallet and workspace limits).

Owners cannot remove the last owner — the org must always have one.

Permissions themselves are workspace-scoped. The RBAC layer checks a granular Permission (for example documents:read, chats:create, connectors:create, settings:update) against the caller's workspace role. Roles are managed at two levels:

• Role Templates (Admin → Role Templates, /admin/role-templates) — admin-defined templates that seed workspace roles, with locked or assignable flags.
• User Groups (Admin → User Groups, /admin/groups) — named groups of users (global or org-scoped) that can grant workspace access at a role. The grant is materialized as real workspace memberships tagged with the group as the provenance, so revocation is exact: deleting the group removes the access it created.
• Org-scoped roles — workspace roles can additionally carry scope = 'organization' for use across an org's workspaces.

Workspaces and credit

Workspaces are attributed to an organization rather than owned by it: a platform admin attaches a workspace (POST /api/v1/organizations/attach/{workspace_id}) and an org owner can detach it. Attached workspaces:

• inherit org-level configuration such as disabled built-in specialists and the org skills tier;
• draw down the org's credit wallet. Funding is a system admin action; org owners control how it is spent with per-workspace credit limits (#409).

Sandbox profile

Which runtime runs a workspace's code execution is chosen per organization, because the organization is the tenant boundary. On Admin → Organizations, the Sandbox profile column lets a system admin pick one of the runtime profiles (Docker, Podman, Kubernetes, or Daytona) for each organization. Every workspace attributed to the organization uses it.

• Empty means the organization uses the deployment's default profile.
• A workspace with no organization also uses the default profile.
• Changing the profile affects new sandboxes only; running ones finish on the profile they started with.
• A workspace still needs code execution switched on (Admin → Workspaces) and members need the code_execution:run permission.

Enterprise authentication (SAML / OIDC / LDAP)

MCintelligentplus supports five authentication mechanisms, stored as provider rows in the database and toggled without a redeploy (AuthProviderType: LOCAL, GOOGLE, OIDC, SAML, LDAP):

The admin portal's Authentication page (/admin/authentication) is the instance-level surface for all five; it also offers discovery (POST /api/v1/admin/auth-providers/discover), connection tests, and SAML metadata handling. AUTH_TYPE in the backend environment is the legacy fallback — provider rows are the single source of truth at runtime.

Organization SSO adds per-org providers on top:

• Org owners add SAML or OIDC providers on Org → SSO Configuration (/org/<slug>/settings/sso). One provider can be active at a time — enabling one automatically disables the others in the same org.
• The org's email domains drive SSO discovery: users whose email matches a claimed domain are routed to the org's provider from the login page's Continue with SSO flow.
• Client secrets and IdP certificates are encrypted at rest, and provider changes are recorded in the audit log (sso.provider.updated).

How to enable

• Organizations are always available. Platform admins create them under Admin → Organizations, then attach workspaces.
• Org-defined agents are gated by SURFSENSE_ORG_AGENTS_ENABLED (default false). The org editor pages 404 while the flag is off, because the chat path does not read definitions.
• Enterprise authentication needs no env flag — add a provider row in the admin portal (or org portal for org SSO) and enable it.

Related PRs

• #260 — Organizations Phase 1: orgs, membership, workspace attribution
• #250 — unified authentication: local, Google, OIDC, SAML, and LDAP together
• #287 — credential unification, encrypted secrets, and the org SSO portal
• #409 — per-workspace credit limits
• #914 — channel permissions (WhatsApp / Teams / Telegram) on the org Members page
• #916 — removed the org-level Teams bot in favour of the system bot
• #953 — org membership revocation purges personal-skill scope
• #975 — org-defined agents and the org skills tier (INT-017/S16-01)
• #1122 / #1125 / #1133 — API clients table, admin API, and org admin pages
• #1195 / #1196 — per-client chat keys and the org security page for full keys