Organizations

An organization is the top-level tenant: every agent, workspace, member, role, and API key belongs to exactly one.

Belonging to more than one

A person can be a member of several organizations, and their standing is decided in the organization the request addresses - the one named in the URL - not in the one they signed in landing on. An Owner of A who is a Viewer in B is a Viewer while working in B. The organization recorded in a session is only a landing preference.

Everything follows from that:

• The organization switcher offers every organization you hold, and switching keeps the page you are on.
• What the panel offers you is resolved in the organization you are looking at, so you are never shown a section that then refuses you - nor hidden one you are entitled to.
• A caller who holds nothing in the addressed organization is refused, and an unknown organization, another tenant’s organization, and one you are not a member of all answer identically - one 403 carrying Organization not accessible. A 404 for only the unknown case would let someone enumerate slugs to learn the deployment’s tenant list. The cost is that a mistyped slug reports “not accessible” rather than “not found”.
• A platform admin is the one exception, and it is checked only after the membership lookup has already failed, so an ordinary member pays nothing for it. See Where a platform admin reaches.
• A management API key is different: it is bound to its own organization and can never address another one, since that organization is its entire authority.

Every deployment has one

A default organization is created by the database migration on first install, and every agent and user is attached to it. A single-tenant deployment therefore needs nothing on this page: it already has an organization, and there is no screen to visit.

The default organization’s display name is not configured from the environment. DEFAULT_ORG_NAME, which re-applied a name on every boot and so undid a rename at the next deploy, is no longer read. With managed services, rename the organization from the Organizations screen.

Listing the organizations you belong to requires org:read and is always available.

Whether the deployment is single-tenant is read from the data, not from a flag. The engine and the panel both count the organizations that exist, rather than consulting an environment variable that can be forgotten or set at the wrong moment.

What that count no longer decides is membership. Signing in never places anyone in an organization, on a single-tenant deployment or a multi-tenant one: an account that arrives without a membership stays without one. For a Google sign-in it goes further - an account with no membership and no valid invitation is refused outright; see Who may sign in with Google. The one account that starts with a membership is the admin seeded at first boot from INITIAL_ADMIN_PASSWORD, which the engine also makes Owner of the default organization on that same boot, so an installation is never left with nobody able to administer it.

Membership is therefore always granted deliberately - from Members and roles, or by an invitation.

SSO domains

Managed services. Federated sign-in is available with Polyant managed services.

Each organization can declare which email domains may sign in with Google. The list sits in the SSO domains column of the Organizations screen: it shows how many domains an organization declares, or No restriction, and opens an editor holding one domain per line.

It is edited by a platform admin and by nobody else - not by an Owner of the organization. A permission that let an organization’s own administrator widen this would let them admit a domain and then admit themselves from it, which is a privilege-escalation surface rather than a delegation.

What the list means:

• Empty restricts nothing. An organization that declares no domains is not a locked organization; it is one that leaves the question to the invitation rule.
• Exact domains only. Matching is a case-insensitive comparison of the whole domain part, so sub.acme.com is not covered by acme.com - add each subdomain as its own entry. A wildcard is refused when you type it, rather than stored as something that could never match.
• It applies to people who are already members of that organization. Someone in two organizations is admitted when either admits them; someone in none is governed by the invitation rule instead. Both rules are in Authentication.
• It constrains who can be invited. An invitation to an address on a domain the list does not admit is refused when you create it, not discovered later by the invitee - see Invitations.
• A platform admin is exempt, so a list that excludes your own address does not lock you out of this screen.
• Password sign-in is unaffected. The list gates the Google provider only.

Every change is written to the management audit trail, recording the resulting list and who saved it. The organization’s rows also record which administrator first added each domain, and that attribution survives later edits: saving the list again does not re-attribute the domains that were already in it.

AI providers and connections

Managed services.

Two separate decisions live here, and they belong to two different people.

Which providers an organization may reach at all is set by a platform admin, from the organization’s row in the Admin Console. It is addressed through the platform tier and never through the organization’s own routes: an Owner who could widen it would be lifting the allow-list they are subject to. The same screen switches individual models off within an admitted provider.

Which credentials the organization holds is set by an Owner or Admin with org.secret:write, on Settings → Organization → Connections (/organizations/{org}/settings/organization/providers; the old provider-credentials address redirects). A connection is a named credential - Produzione, Contratto ricerca - that agent builders bind to a task by name without ever seeing the key. The page lists each connection with what its provider can do and the workspaces it is lent to, starts new ones from a catalog of provider types, speech services included. The organization’s own role, the library embedder, is bound on Settings → Organization → Knowledge. The form asks only for the fields the chosen provider accepts, and refuses a combination that could not authenticate rather than storing it and failing at the first message.

The same page carries the Organization credentials only switch. With it on, agents cannot have connections of their own, and a task bound to one stops until it is bound to one of the organization’s connections.

Whether the organization’s Bedrock connections may use the deployment’s own AWS identity is a third decision, a platform admin’s again: the Bedrock with the deployment’s AWS identity switch on the organization’s Access tab in the Admin Console. Without it, a Bedrock connection needs a key of its own.

Provider connections and roles covers connections, roles, lending and the AWS grant in full.

An organization admitted a provider is not the end of it - the agent’s workspace must have it assigned too. See What a workspace may draw on for the workspace half, and AI Gateway for how the two tiers combine and what an agent is told when they refuse.

Every change on these screens is written to the management audit trail, including the two states of the managed-only switch and of the AWS grant.

Managing more than one

Managed services. Creating, renaming, and deleting organizations is available with Polyant managed services.

The Organizations screen lives in the Admin Console, at /platform/settings/organizations. It is the console’s one deliberately non-platform-admin section: an operator with org:write and the multi-organization licence reaches it without being a platform admin.

The three mutations are gated on both the permission and the feature - the permission alone is not enough, and the request is refused outright when the feature is not licensed. Listing the organizations is gated on the permission only, so the switcher still renders on a deployment that holds one.

From it, an Owner can:

• Create an organization (slug + name).
• Rename one.
• Delete one. This removes the tenant and everything scoped to it; there is no undo.

Only Owners hold org:write. An Admin - who can administer members, workspaces, and agents - deliberately cannot create or delete the organization they work in.

Who can create an organization depends on how the request is authenticated:

The personal-token rule is stricter than the session rule on purpose: a token is a bearer credential that can leak, so it creates a tenant only on the authority of a current platform admin, checked on every call.

Where a platform admin reaches

A platform admin sits above every organization and belongs to none. That is exactly what used to break: the permission layer admitted them, and then a membership lookup - which they fail by definition - refused them. Every route shaped api/organizations/{orgSlug}/… now consults the platform-admin flag once the membership lookup has found nothing, so the reach is uniform rather than a list of individually patched screens: workspaces, members, provider connections, the authorization audit, governance, skills, roles, API keys, invitations, plugin inventory, analytics, the two-factor policy, and renaming or deleting an organization.

GET /api/organizations answers installation-wide for that principal - which is what the Admin Console’s organizations page needs to list anything at all. For everyone else it still answers with the organizations they hold.

Two limits are unchanged, and apply to every principal alike:

• The default organization cannot be deleted by anybody, platform admin included.
• An unknown slug is still refused, with the same Organization not accessible every other rejection carries. The bypass widens who may address an organization; it does not turn a wrong slug into a 404.

A management API key never gets this bypass. It has no user behind it, so there is nothing to check the flag against: its own organization stays its entire authority.

Read that reach literally. A platform admin can enumerate every organization’s provider connections and rotate them - the API returns names, providers and which fields are set, never the stored values, so this is substitution rather than exfiltration. They can also mint a management API key in any organization, carrying the full Owner permission matrix: the usual “you may only hand out permissions you already have” check is exempted for them, because they hold no binding inside the tenant to compare against.

Revoking the flag does not revoke what it issued

Two consequences to plan for before granting it:

• Keys outlive the role. A management API key stamps its organization and its permission set onto the key row itself, and nothing links it back to the person who created it. Taking the platform-admin flag away leaves every key they minted working. Those keys have to be deleted one by one.
• Revocation takes up to five minutes to be everywhere. The flag is cached per process for five minutes. The replica that handles the revocation flushes its own copy at once; every other replica keeps serving the old answer until its copy expires. On a single-replica deployment the revocation is immediate; on a multi-replica one, budget five minutes.

What is scoped to an organization

A plugin and a platform-owned skill are both invisible to an organization until it holds them - a plugin installed from the marketplace or granted from the image, a skill granted - not merely inert. A marketplace plugin a platform admin denies to the organization is absent from its catalogue. Nothing about what the installation runs is disclosed to a tenant that was not given it. See Tools and Skills.

See also

• Workspaces - subdividing an organization.
• Members - who belongs to it and with which role.
• Roles and permissions - what org:write actually grants.
• API keys - the keys a platform admin can mint, and why they outlive the flag.
• Admin Panel overview - where each screen now lives.