Workspace policy

A workspace policy is a small set of rules that the server applies to every document in the workspace, no matter which agent, script or person made the request. It is a Business plan feature; the IP allowlist is Enterprise only.

Who can set it

Workspace owners and admins edit the policy; every member can read it. An agent reads it with get_policy and is told to do so when a publish is refused for policy reasons, because the error and the policy together say exactly which values are acceptable.

REST: GET /api/policy returns the policy plus enabled (whether the plan enforces it), plan, legal_hold_available, ip_allowlist_available and can_edit. PUT /api/policy updates only the keys you send; null clears a rule. Every change is recorded in the audit log as policy.updated with the keys that changed.

In the app, owners and admins edit these rules under Settings, then Access policy. Members can read them there.

Allowed visibilities

allowed_visibilities: a non-empty subset of restricted, unlisted, password and workspace, or null for no restriction. restricted is always allowed, whatever the list says. A publish, set_visibility, or PATCH that asks for anything else is refused with workspace policy does not allow visibility 'unlisted'; allowed: restricted. Use ["restricted"] to require sign-in and permission on everything the company publishes, or ["restricted", "password"] to allow client-facing documents while ruling out links that open for anyone.

Existing documents are not changed when the rule is set; it applies to publishes and changes from then on.

Retention bounds

min_retention_days and max_retention_days, each a whole number of days or null. The maximum must be at least 1 (0 would mean "forever", which is the thing a maximum forbids), and the minimum may not exceed the maximum.

• Explicit values outside the window are rejected: set_retention, PATCH with retention_days, and a publish that names a retention other than the default.
• A maximum forbids keep-forever. "Keep" (the warning email link and POST /api/docs/{id}/keep) extends a document to the maximum instead.
• A publish that relies on the default retention is clamped into the window rather than refused, so agents that never mention retention keep working.

The full interaction is described in Expiry and retention.

Secret scanning

secret_scan is off, warn or block. When it is on, every text file written to a document, at publish time and on every update, edit, patch and added file, is scanned for content that looks like a credential:

• access keys and secret keys for cloud providers;
• personal access tokens for source-control and chat platforms;
• live keys for a payment provider;
• API keys from common hosted services;
• PEM private key blocks;
• generic api_key = "...", client_secret: '...', password = "..." assignments with a long value.

Obvious placeholders (xxxx, <your-key>, changeme, ${VAR}) are ignored. Binary files, images and media are not scanned. The exact patterns are not published.

• warn: the write goes through, and a doc.secret_warning event is recorded in the audit log with the file path and the category of what was found, never the value itself.
• block: the write is refused with a message naming the file and the category, and telling the agent to remove the values or move them to environment variables and try again. Nothing is stored.

Scanning is a safety net, not a guarantee; content that does not match a known shape is not caught.

Publishing folders as sites

publishing decides whether folders may be published as sites. It is public, signed_in or off, and public is the default. In the app it is Publishing folders as sites under Settings, then Access policy.

Turning Published off is always accepted. The rule does not rewrite folder settings: set it back to public and the sites are served as they were. It applies to folders in My documents as well as in roots, and to sites on a custom domain. With off, /robots.txt on a custom domain stops listing the folder sitemaps.

GET /api/folder-meta and GET /api/folder-view return publishing_policy, and publish_blocked: "policy" when the rule is off, so a client can explain why Publish is unavailable. The Publish dialog shows that note and leaves out the public option when the rule is signed_in.

This rule is about folder sites only. Document visibility is governed by Allowed visibilities.

IP allowlist (Enterprise)

ip_allowlist: a list of CIDR ranges such as ["203.0.113.0/24", "2001:db8::/32"], or null for no restriction. A single address is accepted and stored as a /32 or /128. Invalid entries are rejected with the reason.

When the list is set, requests from outside it are refused with a 403:

• every signed-in request to the app and the /api endpoints, with your workspace only allows access from approved networks; <ip> is not on the allowlist;
• every view of a Restricted document on the content host, including custom domains, with this document is restricted to approved networks.

Each refusal is recorded in the audit log as policy.ip_denied with the address. Unlisted and password documents are not affected by the allowlist, since their readers are not identified by workspace. Agent calls to the MCP server authenticate with a token and are not filtered by the allowlist today.

Check the list before you save it: a mistake locks you out of the app until you reach it from an allowed address. Owners on the allowed network can always change it.

Legal hold

Legal hold is set per document rather than in the policy, but it is part of the same Enterprise feature set: a held document cannot be deleted or purged and never expires. See Expiry and retention.

Below the Business plan

A policy saved while a workspace was on Business is kept if the plan lapses, but it stops being enforced until the workspace is on Business or Enterprise again. GET /api/policy shows enabled: false in that state.