Workspace administration

A workspace is where your team’s data lives — tables, records, charts, dashboards — and it is the permission boundary around all of it. This guide covers the administrative surface of a single workspace: its members, its groups, its settings and branding, its home page, and its usage limits. The organization above the workspace (invitations, billing, backups, security policy) has its own guide: Organization administration.

If you only remember one thing: a workspace never contains strangers. Everyone in it is first a member of the owning organization; workspace membership is a grant on top of that. So you add existing organization members to a workspace — bringing somebody genuinely new in always starts with an organization invitation.

---

Who can do what

Action	Grants	Held by default
workspace:members:read	See the member list	Admin, Member, Reader
workspace:members:manage	Add members, change roles, deactivate, reactivate	Admin
groups:read	See groups and their members	Admin, Member, Reader
groups:manage	Create, edit, delete groups; manage group membership	Admin
customization:read	See workspace branding and the configured home page	Admin, Member, Reader
customization:manage	Edit branding, collaboration settings, and the home page	Admin
limits:manage	View the Limits & usage page; configure per-resource limits	Admin
tables:read	List system entities and their items	Admin, Member, Reader

These are ordinary actions in the roles model, so a custom role can grant any of them to someone who isn’t a full admin.

One deliberate exception to the table: the member endpoints are also open to the organization above you. Every operation on GET /workspaces/{workspaceId}/members and its siblings accepts either the workspace action or org:workspaces:manage on the owning organization — that is how an org owner/admin can administer a workspace’s membership without being in the workspace. They still cannot open it or read its data; see the authorization guide for that boundary.

---

Members

Manage members in Workspace Settings → Members. Every member has exactly one baseline role:

Role	In one line
Admin	Full control of the workspace and its data.
Member	Create and edit data, tables, charts, queries.
Reader	View-only.

What each role actually grants, and how custom roles layer on top, is covered in Authorization & permissions.

Adding a member

Add Member (POST /workspaces/{workspaceId}/members) grants an existing, active organization member access to this workspace, with the role you pick at add time. The dialog lists organization members who don’t already have access. The request is refused (409) if the person is not an active organization member or is already an active member of the workspace.

If the person you want isn’t in the list, they aren’t in the organization yet — ask an org owner/admin to invite them. An invitation can pre-select workspaces and roles, so joining the organization and getting workspace access can happen in one step.

Changing a role

Edit role (PATCH /workspaces/{workspaceId}/members/{userId}) changes a member’s baseline role. Two protective rules apply when a workspace admin does it:

• You cannot change another admin’s role (admins are peers, not each other’s superiors).
• You cannot demote the workspace’s last active admin.

An org owner/admin acting through the organization console can do both — the organization axis is deliberately the recovery path when a workspace locks itself out of admins.

Deactivate, reactivate — and what “remove” means

There is no hard delete for a workspace membership. The Remove from workspace action (DELETE /workspaces/{workspaceId}/members/{userId}) is a soft removal (deactivation):

• The person immediately loses access to the workspace, and their API tokens for this workspace are revoked at the same time — credentials never outlive the membership.
• Their membership row is kept, marked Inactive. Switch the Members tab’s filter to All members (the list endpoint’s includeInactive option) to see deactivated members.
• Records they created, comments, and audit history are untouched — nothing they did is deleted with them.

The same peer-admin and last-admin rules apply as for role changes: a workspace admin cannot deactivate another admin, nor the last active admin; an org owner/admin can.

Reactivate (POST /workspaces/{workspaceId}/members/{userId}/reactivate) re-enables a deactivated member with the role they had before. It requires the person to still be an active member of the owning organization — someone deactivated at the organization level must be restored there first. Reactivating an already-active member returns a 400.

Note

Deactivation at the organization level cascades: when someone is deactivated from the organization, they are automatically deactivated from every workspace it owns. Reactivating them in the organization does not automatically restore their workspace memberships — those are reactivated per workspace, deliberately.

---

Groups

Groups (Workspace Settings → Groups) are named sets of workspace members. They exist to let you say “this team” once and reuse it:

• Record scopes — on a private table, a role with a group scope sees records owned by anyone who shares a group with the holder. Groups are the definition of “team” for that rule. See Authorization & permissions.
• Record sharing — a record can be shared to a whole group instead of one person at a time.
• Group reference fields — fields in your tables can reference groups (see System entities below), e.g. an “Owning team” column.
• Page arrangement — a group can have its own home page, its own record page layout per table, and its own saved list views, so each team sees the fields and tiles it works with foregrounded. See Page layout below.

Caution

Those last two are different kinds of thing, and it is worth keeping them apart: the first three bullets are about access — who can see which records. The last one is about arrangement — how the same records are laid out. Targeting a group’s layout never widens or narrows what anyone can see, and choosing which group’s layout you look at never changes your access: you keep everything shared with all of your groups either way.

Anyone in the workspace can see groups and their membership (groups:read); creating, editing, and deleting them requires groups:manage (admins by default).

The API surface mirrors the UI: GET /groups lists groups (optionally including inactive ones), POST /groups creates one (names must be unique), PATCH /groups/{groupId} renames it, edits the description, or toggles active status, and GET /groups/{groupId}/members / POST /groups/{groupId}/members / DELETE /groups/{groupId}/members/{userId} manage who’s in it. Only active workspace members can be added.

Caution

DELETE /groups/{groupId} is permanent: the group and all its memberships are gone. Any access that flowed through the group — group record scopes matching via it, shares granted to it — stops applying immediately. Deactivating a group (via its active flag) is the reversible alternative.

---

Workspace settings

Workspace Settings → Appearance (visible to customization:manage holders) is where the workspace’s look and collaboration behaviour live. The underlying settings are read with GET /workspace/settings (readable by everyone via customization:read) and written with PUT /workspace/settings.

Branding: name, colours, logo

• Display name — replaces the product name in the navigation bar for everyone in this workspace. Leave it empty to keep the stock name.
• Brand colours — a primary and a secondary colour (hex values) that drive the whole theme, with a live gradient preview.
• Logo — PNG, JPEG or WebP, up to 1 MB. Uploading goes through POST /workspace/settings/logo, which issues a direct upload slot; the returned storage key is then saved as the settings’ logoKey. Keys from other workspaces are rejected.

Note

The settings write is a full replace of branding: fields omitted from the save are cleared back to defaults. The UI handles this for you, but if you script against the API, always send the complete branding you want to keep — including the current logoKey, or the logo is cleared.

Collaboration settings

The Collaboration section (same tab) holds live-collaboration switches. There is one today: “Show who is editing a field” (fieldPresenceEnabled). While someone has a field open for editing, others viewing the same record see a live indicator with their name — only who and where is shared, never what they are typing. It is on by default, applies to the whole workspace, saves immediately on toggle, and (unlike branding) is left unchanged when omitted from a settings write. People may need to reload open tabs to pick up a change.

The workspace home page

Every workspace has a home page. Until an admin configures one, everybody sees the built-in default (quick links plus their own recent items). An admin can replace it with a curated page of tiles, edited in place on the home page itself (the edit controls appear for customization:manage holders):

Tile kind	Shows
chart	A saved chart
table	A saved query rendered as rows
quickLinks	In-app links — the built-in list or a curated one
recentRecords	The newest records in one table
myRecents	The viewer’s own recently visited items
markdown	A block of admin-authored text

Tiles share the dashboard grid (12 columns, up to 40 tiles). Under the hood: GET /workspace/homepage returns the configuration (viewers whose role can’t read it simply get the default page — never an error), PUT /workspace/homepage replaces the whole tile list, and DELETE /workspace/homepage discards the configuration and reverts everyone to the built-in default.

A home page can never hide anything: each viewer’s tiles render under their own permissions, so a chart or table a person cannot see is simply not shown to them.

One home page per team, if you want one

The Arranging for selector in the home page editor lets you compose a page for a group instead of for everyone. A group’s page is a separate document: editing it never touches what everyone else lands on, and a group without one inherits the workspace’s. Removing a group’s page puts it back on the workspace’s.

Record page layouts work the same way — the layout editor on a table’s schema page carries the same selector, so Sales can open a Deal with pipeline fields at the top while Finance foregrounds billing (see Records). Saved list views have a third audience for the same reason (see Views).

Two things to know:

• You do not have to be in a group to compose for it — customization:manage is the only requirement, since this is workspace configuration.
• Under the hood these are the same endpoints with an ownerScope (and ownerGroupId): GET/PUT/DELETE /workspace/homepage and .../record-layout. Without ownerScope a GET returns whatever applies to the caller; with it, the one document you asked for.

Page layout: your group’s arrangement

Because a home page and a record page must resolve to exactly one layout, somebody in two groups needs a tiebreak — and we do not guess one. Each person chooses, under Page layout in the app bar, which of their groups’ layouts they see. The choice sticks as their default (per workspace, since groups are workspace-scoped) and applies to the home page, record pages and which saved view a table opens with.

Details:

• Someone in exactly one group gets their team’s layout without choosing anything — one candidate is not a tiebreak. They can still pick “Workspace default” to opt out.
• Someone in several groups sees the workspace layout until they pick one.
• The control is hidden entirely for anyone in no groups.

Caution

This is not “acting as” a group. It changes how pages are arranged and nothing else: you continue to see every record shared with every group you belong to, whichever layout you are looking at. If you need to see the product as another person sees it, that is a support-session feature, not this one.

---

System entities

System entities (GET /system-entities, requiring only tables:read) are the built-in, read-only directories that your tables can reference — as opposed to tables you create yourself. There are two:

• Users — the workspace’s active members (id, name, email). Use it for reference fields like Owner or Assigned to.
• Groups — the workspace’s active groups (id, name, description). Use it for team-assignment fields.

When you add a reference field to a table, these appear alongside your own tables as possible targets. GET /system-entities/{entityId}/items returns the current items (active members or active groups) and is what the app uses to display and pick reference values. System entities cannot be edited, extended, or deleted — their content is simply a live view of workspace membership and groups, so deactivating a member or group updates every field that references them. See Tables & fields for reference fields in general.

---

Limits and usage

Some activity in a workspace is metered against daily allowances — currently:

Measure	Counts	Counted at
query.executions	Ad-hoc query executions against workspace data	Workspace total
search.executions	Global-search executions	Workspace total

(A metered inbound-webhook measure returns with the Flows hook ingress.)

What happens at the limit: further requests of that kind are rejected until the daily window resets. Nothing is disabled and nothing needs re-enabling — the counter simply runs out and comes back.

Where a ceiling comes from: the limit ladder

Every effective limit is bound by exactly one of four tiers:

The limit ladder. The value actually enforced is the tightest tier — and every usage row tells you which tier that was.

The Limits & usage page

Workspace Settings → Limits (GET /workspace/limits/usage, visible to limits:manage holders) shows, per counter: the measure, current usage against the effective ceiling, which tier set that ceiling, and when the window resets. Showing the tier is the point of the page — it tells you what to do next:

Ceiling set by	What to do to raise it
This resource (T1)	Raise it yourself, up to the maximum above it
Organization (T2)	Ask an org admin — see Organization administration
Plan (T3)	An upgrade or an increase request
Platform (T4)	Cannot be raised

Counters whose resource has since been deleted still appear (they keep consuming the workspace total), and organization-level figures are simply the sum of its workspaces’ counters — there is no separate counter above the workspace.

Configuring one resource’s limit

GET /resource-limits/{measure}/{resourceType}/{resourceId} (readable with flows:read) returns the full resolution for one resource — the enforced value, the tier that bound it, the maximum you may configure, what is currently configured, and current usage. A workspace admin (limits:manage) can set the resource’s own T1 value with PUT /resource-limits/{measure}/{resourceType}/{resourceId}:

• The value must not exceed the maximum in force above it — a request that does is rejected with the real maximum in the error, so you learn the ceiling rather than silently getting a clamped value.
• Sending null clears the configuration, so the resource inherits the maximum.
• A stored value that later ends up above a tightened maximum is clamped, never grandfathered — the page shows both the configured and the enforced value in that case.

Usage alerts

Each counter alerts as it approaches its ceiling: by default at 75% and 100% of the effective limit, delivered through the notification centre to the people who can act on it. The same PUT lets you customise the stops per resource — as percentages or absolute counts (“alert at 10,000 of our 12,000”), an empty list to disable alerting for that resource, or a reset back to the implicit defaults.

---

FAQ

Q: I removed someone from the workspace — is their data gone?

No. Removal is deactivation: their access and workspace API tokens end immediately, but their membership row (reactivatable at any time), their records, comments, and audit history all remain.

Q: I’m a workspace admin but can’t remove another admin.

By design — workspace admins are peers. Ask an org owner/admin, who can change or remove any workspace member from the organization console.

Q: Somebody from the organization appeared in our member list without an invitation.

Org owners/admins can add themselves (or others) to any workspace the organization owns — that’s the deliberate recovery/administration path, and it always shows up in your member list as an ordinary membership, so nobody has invisible access. See Organization administration.

Q: Why don’t I see the Limits or Appearance tabs?

They only render if you hold limits:manage / customization:manage respectively — admin-tier actions by default. A custom role can grant either on its own.

Q: A webhook stopped being accepted mid-day. What happened?

Almost certainly a daily allowance ran out — check Workspace Settings → Limits. The row for webhook.invocations shows how much was used, which tier set the ceiling, and when the window resets. Nothing needs re-enabling; acceptance resumes when the window resets or the ceiling is raised.