Organizations
An organization is a customer: the outermost boundary, with nothing shared across organizations. The tenancy page explains what that isolation means. This page is about the administrator's side of it — how one comes into being, and what you can change once it has.
An organization is created at signup, not by an administrator
This is the first thing to understand, because it is not what most platforms do.
There is no "create an organization" screen and no administrator-facing endpoint that creates one.
The organization is created as a side effect of creating the first account in it: the name you type
into the organization name field on the signup form becomes the organization, you are recorded as
its owner, and the whole thing happens inside the same transaction that creates your account. If no
name is supplied, the organization is called Default Organization.
Two consequences worth planning around:
- Whoever signs up first owns the organization. If that should be a particular person, they should be the one to sign up, not an assistant setting things up on their behalf.
- A second organization means a second signup, redeeming a key that is not yet bound to an organization. There is no in-product action that creates one from inside an existing organization.
A person can belong to more than one organization — GET /users/org-list returns the set, and the
application's organization switcher reads it — but each of those memberships came from a separate
signup or invitation, never from a create action.
What you can configure
Settings → Organization (/settings/org) reads and writes the organization through
GET /settings/organizations/{id} and PUT /settings/organizations/{id}. The screen has three
sections, and only some of it is editable.
| Section | Field | Editable? |
|---|---|---|
| Org profile | Organization name | Yes, by an organization administrator |
| Org profile | Primary domain | Yes, by an organization administrator |
| Org profile | Tenant ID | No — shown for reference |
| Identity provider | Single sign-on and directory provisioning status | Displayed only |
| Deployment posture | Cloud, on-premises or air-gapped | Displayed; the screen says to contact your account team to change it |
The update endpoint accepts name, primaryDomain, deploymentMode (one of cloud, on_prem,
air_gapped), and status objects for the identity provider and directory provisioning. The screen
gates the first two behind an organization administrator and the deployment posture behind the
platform administrator, which is why the posture control reads as informational to everyone else.
The environment health panel
Settings → Organization has an environment-health section backed by
GET /settings/organizations/{id}/health. It currently returns an empty list of components and a
timestamp, and the screen hides the section as a result. It is a place a future health check will
report into, not a health check. Nothing depends on it, and an empty panel is not a fault.
The organization's join key
Every organization has one reusable, non-expiring access key, which is what lets a colleague sign up straight into your organization rather than bootstrapping their own.
GET /settings/organizations/{id}/access-keyreturns it, and creates one lazily for an organization that predates the feature. Only an organization administrator may read it; anyone else gets403 "Only a super admin or org admin can view the org access key."POST /settings/organizations/{id}/access-key/invitewith an email records that address on the organization's allow-list and emails a signup link with the key already filled in.
The key alone admits nobody. Signup checks for the key and an allow-list entry for that exact
email address, and refuses with "This access key is registered to an org which this email hasn't been invited to" when only the key is present. That is deliberate: a key that leaked in a
screenshot or a forwarded message is not a way into your organization.
In practice you should never hand the raw key out. Use the invitation flow on members and invitations, which records the allow-list entry and sends the link for you, so the invitee never sees or handles the key.
What is counted at the organization
Two things are organization-wide rather than per project, and both are worth knowing before you decide how many projects to create:
- Request quotas. The shipped defaults are 120 requests per project and 600 per organization per
sliding 60-second window, where
0means unlimited. Two teams in one organization can therefore exhaust each other's headroom. See quota and credits. - Audit and lifecycle records, which carry the organization on every entry. See lifecycle and audit — including the honest limits on how long those records survive.
Next
Once the organization exists, the structural decision is the next one: departments and projects.