Organization administration

An organization is the management and billing grouping above workspaces. It owns every workspace inside it, holds the member roster people are invited into, and carries the controls that apply across workspaces: security policy, feature toggles, quota maxima, usage reporting, backups, single sign-on, and billing. This guide is for organization owners and admins working in Organization Settings.

If you only remember one thing: organization roles are management-plane only. Being an org owner or admin lets you administer workspaces — create them, rename them, manage their members, even delete them — but grants no access to the data inside any workspace. Reading or writing records always requires your own workspace membership.

The organization layer vs workspaces

The organization owns its workspaces and the cross-workspace controls. Data access lives entirely inside each workspace.

Membership is org-first: people are invited to the organization, and workspace access is a grant layered on that org membership. Ending someone’s org membership therefore ends their access to every workspace the organization owns (see Members below).

Who can do what

Organization roles are owner, admin, and member, and they nest: owner ⊇ admin ⊇ member. Under the hood each role grants named org actions — the API and this guide quote them exactly:

Action	Grants	member	admin	owner
`org:read`	See the organization, its member list, its workspace list	✓	✓	✓
`org:settings:manage`	Rename the org; feature toggles; security policy		✓	✓
`org:members:manage`	Invite, change roles, deactivate, reactivate members		✓	✓
`org:workspaces:manage`	Create/rename/delete workspaces; manage their members		✓	✓
`org:directory:read`	The cross-workspace user directory		✓	✓
`org:sso:manage`	SSO connections		✓	✓
`org:domains:manage`	Verified email domains		✓	✓
`org:billing:manage`	Billing, plan, and usage reporting		✓	✓
`org:backups:manage`	Workspace backups and restores (including viewing them)		✓	✓
`org:limits:manage`	The organization’s quota maxima		✓	✓
`org:delete`	Delete the organization itself			✓

On top of the action grants, a few relationship rules always apply:

Only owners may grant (or invite to) the owner or admin role.
Admins cannot modify or remove other admins or owners.
The last active owner can never be demoted or deactivated.
Reactivating a deactivated owner or admin is owner-only (restoring the row restores its powers).

Organization members

Organization Settings → Members lists the roster (GET /organizations/{organizationId}/members, with an option to include deactivated members). Role changes go through PATCH /organizations/{organizationId}/members/{userId}, subject to the relationship rules above.

Deactivation (DELETE /organizations/{organizationId}/members/{userId}) is a soft removal, and it cascades: the person is immediately deactivated from every workspace this organization owns, and their workspace API tokens are revoked. Their user account, their records, and their history are untouched.

Reactivation (POST /organizations/{organizationId}/members/{userId}/reactivate) restores the org membership with its previous role. It does not automatically restore workspace memberships — those are reactivated per workspace, deliberately, so returning someone to the organization doesn’t silently re-open every workspace they once had.

Invitations

Bringing somebody new into the organization starts with an invitation (Members tab → Invite, POST /organizations/{organizationId}/invites):

You set their organization role (inviting as owner or admin requires you to be an owner) and, optionally, workspace grants — a list of workspaces and a workspace role in each, applied the moment the invitation is accepted. That makes joining the org and getting workspace access a single step. An invitation with no grants joins the organization only.
The invitation is addressed to an email, and also carries a shareable link token. The token is shown exactly once — on the create and resend responses — because only a hash of it is stored.
Invitations expire after 7 days.

While an invitation is pending you can:

Edit it (PATCH /organizations/{organizationId}/invites/{inviteId}) — change the role or replace the workspace-grant set. Granting owner/admin stays owner-only, as on create.
Re-issue the link (POST /organizations/{organizationId}/invites/{inviteId}/resend) — rotates the token and extends the expiry, returning a fresh link. The previous link stops working immediately, which also makes resend the way to kill a link that leaked without revoking the invitation.
Revoke it (DELETE /organizations/{organizationId}/invites/{inviteId}).

How invitees accept

There are two paths, and the Invitations page in the app serves both:

Signed in, by email match — GET /org-invites/pending lists every pending invitation matching the signed-in user’s email, and POST /org-invites/{inviteId}/accept accepts one. The email must match the invitation’s.
Via the shareable link — the link lands on the Invitations page and calls POST /org-invites/token/{token}/accept, which needs no session: if the visitor is signed in with the matching email it accepts immediately; otherwise it returns the invitation’s details so the app can walk them through signing in or registering first, then accept.

Accepting applies the org membership and every workspace grant atomically — the person lands with exactly the access the invitation described.

The organization directory

Organization Settings → Directory (GET /organizations/{organizationId}/directory, gated by org:directory:read) is the deduplicated union of the organization’s members and the members of all its workspaces — one row per person, showing their org role (if any) and every workspace membership they hold in this organization. It is the “who has access to what, everywhere” view, and because it reveals cross-workspace membership it sits at the management tier rather than being visible to every member.

Workspaces

Organization Settings → Workspaces lists every workspace the organization owns (GET /organizations/{organizationId}/workspaces), with member counts and whether you are a member of each.

Create (POST /organizations/{organizationId}/workspaces) — requires org:workspaces:manage. The creator becomes the new workspace’s first admin member — the one case where org rank leads to workspace access, and only because the creator provisioned it.
Rename / toggle deletable (PATCH /organizations/{organizationId}/workspaces/{workspaceId}) — a management-only surface.
Manage members — the same member panel workspace admins use, addressed at any workspace in the list, membership or not. See Workspace administration.
Join workspace — adds you as a workspace admin, as an ordinary, visible membership. Administering a workspace and having access to its data are deliberately separate; this is the explicit, auditable way in.

Deleting a workspace — the two-step flow

Hard-deleting a workspace is guarded three ways: a deletable flag, a short-lived confirmation token, and retyping the workspace’s name.

The workspace must be marked deletable. Workspaces are created with deletable: false unless you say otherwise; the flag is meant for demo/test workspaces and is toggled (reversibly) by org owners/admins on the Workspaces tab. Both delete endpoints refuse outright (409) for a non-deletable workspace — so marking a workspace non-deletable is a real safety interlock, not a UI hint.
Request deletion (POST /organizations/{organizationId}/workspaces/{workspaceId}/delete-request) issues a one-time confirmation token valid for 15 minutes. Only the most recent request per workspace counts — issuing a new token invalidates any previous one.
Confirm (POST /organizations/{organizationId}/workspaces/{workspaceId}/delete) with that token plus the workspace’s exact current name, retyped as an explicit statement of what is being destroyed. A name mismatch is a 400, a missing/superseded token a 409, an expired one a 410.

The organization itself can also be deleted (DELETE /organizations/{organizationId}) — owner-only, and refused while the organization still owns any workspace.

Feature toggles

Organization Settings → General carries the organization’s self-serve feature switches (GET /organizations/{organizationId}/features, written with PUT /organizations/{organizationId}/features by org:settings:manage holders):

AI record writes via MCP (mcpRecordWritesEnabled) — whether connected AI clients get the record write tools in this organization’s workspaces. Off by default. Turning it on only exposes the tools: every write still runs under the individual user’s own permissions, validation, and audit logging. See AI assistants.
Billing/payments (billingPaymentsEnabled) appears in the same response but is read-only — it is operator-managed and simply tells the app whether to show the billing surface.

Security policy

Organization Settings → Security (GET /organizations/{organizationId}/security / PUT /organizations/{organizationId}/security, managed by org:settings:manage holders) holds one policy today: Require multi-factor authentication (requireMfa).

When on, every member must satisfy MFA — an authenticator app or email codes, or signing in with a passkey — to access this organization’s workspaces or call its organization endpoints. Enforcement happens at token issuance and on org-scoped requests, so members without MFA are prompted to set it up at their next sign-in or session refresh, and existing access expires within 30 minutes of the policy turning on. Single sign-on users are exempt — their identity provider is responsible for MFA.

Enabling is refused (409) until you and every active organization owner are MFA-capable, and the refusal names the owners who still need to enrol — the policy can never lock out the people who administer it. Individual MFA setup is covered in Account security.

Limit policies (quota maxima)

Organization Settings → Limits (GET /organizations/{organizationId}/limit-policies, written with PUT /organizations/{organizationId}/limit-policies by org:limits:manage holders) is tier T2 of the limit ladder described in Workspace administration. These are limits on limits — they never count traffic themselves; they bound what workspace admins may configure below you. Per metered measure (ad-hoc query executions, global-search executions) you can set:

Max per workspace — the most any one workspace may hold as its total.
Max per resource — the most any single resource may be configured to (relevant for measures counted per resource, which return with the Flows hook ingress).

Both sit under the plan entitlement above them: a value beyond the entitlement is rejected with the real ceiling in the error, so this control can only ever tighten. Clearing a field falls back to the entitlement. A workspace value already configured above a maximum you tighten is clamped, never grandfathered.

Usage reporting

Organization Settings → Usage (GET /organizations/{organizationId}/usage, gated by org:billing:manage) shows the organization’s metered resource usage across all its workspaces: a live current reading plus month-by-month history (up to 24 months). Gauge measures show where they stand right now; activity measures accumulate month-to-date. The figures are usage only — no pricing; money lives in Billing.

Backups and restore

Organization Settings → Backups is the disaster-recovery surface for whole workspaces. Everything here — including just seeing the list — is gated by org:backups:manage, because backups are a control surface with no member-facing use.

Taking a backup

POST /organizations/{organizationId}/backups queues an asynchronous export of one workspace: its schema, records, saved queries and charts, roles, groups, record shares, and attachments, into an organization-scoped backup artifact. List and inspect them with GET /organizations/{organizationId}/backups and GET /organizations/{organizationId}/backups/{backupId} (which includes live job progress and non-fatal warnings).

Facts worth knowing before you rely on it:

A backup is per-batch consistent, not a point-in-time snapshot: rows written while the export runs may or may not be included. Prefer quiet periods for backups you care about.
One backup of a given workspace runs at a time (a second request for the same workspace gets a 429 — a repeat export would redo all the work for the same data). Different workspaces back up concurrently, up to a per-organization ceiling on how many jobs one tenant may have in flight; going over that also gets a 429. Preparing a download is budgeted separately, so it never fails because a backup is running.
There is a cap on stored backups (409 — delete an old one first, via DELETE /organizations/{organizationId}/backups/{backupId}).
A backup outlives its source workspace — including through the two-step workspace delete.
Restorability attaches to the backup’s format version, not its age: a backup remains restorable while its format is current, and for one year after that format is superseded (each backup’s expiry field shows the date, or none while the format is current). Past that, restore requests are refused.

Backing up on a schedule

A workspace can back itself up on a repeating cadence instead of waiting for someone to remember. POST /organizations/{organizationId}/backup-schedules creates one from a standard 5-field cron expression evaluated in UTC; list, edit and remove them via GET, PATCH …/{scheduleId} and DELETE …/{scheduleId}. Each firing runs exactly the export the button runs.

One schedule per workspace, and it may not run more often than once an hour — backing up a whole workspace is heavy, and a denser cadence would collide with its own previous run.
Each schedule keeps its own last retainCount backups (7 by default) and deletes its older ones just before each run. This is what lets a recurring schedule keep working instead of stopping the first time it meets the stored-backup cap. Backups you took yourself are never deleted by a schedule, and neither are another schedule’s.
Your schedules have to fit inside your organization’s backup limit, together. Creating or raising a schedule whose retention would take the combined total past that limit is refused with a 409 explaining what will fit — one slot is always kept free for backups you take by hand. Being refused here is much better than the alternative: schedules that overcommit would run for a while and then quietly stop refreshing.
Missed runs collapse. If a schedule was due several times while something was wrong, it runs once when service resumes — it does not catch up in a burst.
A run that can’t start is reported, and retried soon. If the organization is at its backup limit or job ceiling, the schedule records why (visible as lastError) and tries again within about ten minutes rather than waiting for its next scheduled time — so several workspaces sharing one nightly cadence all get backed up, just staggered as the queue drains.
Deleting a schedule keeps the backups it took. They become ordinary backups.

Downloading a backup

A backup is stored as many files, so downloading one packages them into a single .tar archive first. POST /organizations/{organizationId}/backups/{backupId}/download starts that packaging (or returns the finished archive if there already is one); poll GET on the same path until its status is ready, then fetch its downloadUrl.

The link is short-lived and grants access to the whole backup — treat it like a password, and don’t paste it anywhere shared.
The packaged archive is deleted 24 hours after it is prepared. That doesn’t affect the backup itself: ask for the download again and it is re-packaged.
The archive contains the backup exactly as stored — the manifest, the per-table data files, and your attachments. It is intended for keeping an off-platform copy; restoring is still done through the restore endpoint below.

Restoring

POST /organizations/{organizationId}/backups/{backupId}/restore queues an asynchronous restore; track it with GET /organizations/{organizationId}/restores/{jobId}.

One reconciliation happens on the way in: access-granting rows — role assignments, group memberships, record shares — that reference people who are no longer active organization members are dropped, and each drop is reported as a warning on the job. Data is never dropped for this reason, only grants.

Also at the organization level

Single sign-on and verified domains — OIDC connections, domain claims, and login policy (org:sso:manage / org:domains:manage) are covered in Enterprise SSO.
Billing — plan, payment methods, and invoices (org:billing:manage) are covered in Billing.

FAQ

Q: I’m an org owner. Why can’t I open a workspace’s records?

Because org roles never grant data access. Use Join workspace on the Workspaces tab to add yourself as a workspace admin — an ordinary membership that the workspace’s own member list shows, so nobody has invisible access.

Q: We deactivated someone from the organization. What exactly did they lose?

Everything, immediately: their org membership, every workspace membership in this organization, and their workspace API tokens. Their account and the data they created remain. Reactivating them restores only the org membership — workspace access is restored per workspace.

Q: An invitation link was forwarded to the wrong person. What do I do?

Use Re-issue (resend) to rotate the token — the old link dies instantly and you get a fresh one — or revoke the invitation entirely. Note the emailed-identity check still applies on the signed-in accept path, but the shareable link is designed to let a new user register, so treat the link itself as the credential.

Q: The workspace delete button is greyed out / the API returns 409 “not deletable”.

The workspace isn’t marked deletable. That flag (off by default) is the first interlock of the delete flow — toggle it on the Workspaces tab if you really mean to delete, then run the two-step confirmation within 15 minutes.

Q: Can I restore a backup over the workspace it came from?

No — restore always creates a new workspace. If the goal is replacement, restore first, verify the result, then delete the old workspace via the two-step flow (after marking it deletable).

Q: Why can’t I enable “Require MFA”?

The server refuses until you and every active owner have a verified second factor or a passkey, and the error lists who is missing. Get those owners enrolled (see Account security), then toggle again.

Open the app