Access & sharing

Five access levels, set per site and changeable at any time. The restricted ones work the way sharing a document does: by email address, or with everyone at a company by its domain, with no account needed until the person opens the link.

The five levels#

unlisted is the default because it matches what people usually mean by “send me a link”. Set the level on publish with --visibility, or change it later on the site’s page under Access, or from an agent with PATCH /api/v1/sites/:id or the MCP set_visibility tool; a change applies on the next request. Publishing again without --visibility leaves the level alone, so a change made here survives the next publish. A workspace’s owner can rule out the more open levels for every site in it: see the sharing limit.

A workspace’s sharing limit#

An owner can set the most open level any site in the workspace may have, under Members & settings → Sharing limit. Restricted at most, for example, means nothing there is public, unlisted, or behind only a password. There is no limit until an owner sets one, and it works the same on every plan.

• From most open to least: public, unlisted, password, restricted, private. Password counts as more open than restricted because anyone holding it gets in without signing in.
• Every publish and every change of level is held to it: from the dashboard, the CLI, the API or the MCP tools, and from an API key as much as a person. A level above the limit is refused with a 403 that names the limit and the levels it allows, and the site stays as it was.
• A new site published without a level is unlisted as usual. Under a lower limit it takes the most open level left that needs no password: restricted under Password at most or Restricted at most, and private under Private only. The publish reply’s visibility says which.
• The dashboard greys out levels above the limit on a site’s Access card and in the upload form, so you cannot pick one and then be refused.
• Claiming a page that was published without an account brings it in the same way: unlisted if the limit allows it, otherwise the workspace’s default under the limit. The claim page shows which before you claim.
• Lowering the limit while some sites are above it changes nothing until you confirm. The settings page lists those sites; Bring these sites down moves exactly those sites to the new default and sets the limit, in one step. Each site’s change is recorded in the audit log, and the CDN drops its cached pages. Raising or removing the limit later does not move any site back up.

The showcase#

The showcase is one page on colophon.fyi listing public sites their owners chose to show, newest first, each with its title, the workspace’s name and its link-preview card. A site is on it only because an owner put it there: on the site’s page under Showcase, or with "showcase": true on PATCH /api/v1/sites/:id or the MCP set_showcase tool signed in as one. An API key cannot: it is a person’s decision.

• Only a public site can go there, and only in a workspace whose sharing limit allows public.
• It is listed once its live version’s links have been checked for malware and phishing and passed, no version is held for review or was taken down, a day has passed since it became public and since its name or its front page’s title last changed, and the workspace is a week old. A change to either takes the site off the showcase for a day, whatever published it: a publish, a rollback or an approval. A deploy that changes neither leaves it listed. Until then the switch stays on and the site’s page says what it is waiting for.
• It leaves at once if it stops being public, expires, is deleted, has a version held or taken down, or its workspace is suspended. Making it anything but public also turns the switch off, so making it public again does not put it back.
• Listing a site changes nothing about the site. Search engines still follow the workspace’s own setting, and the showcase’s links to it say nofollow.
• Colophon can take any site off, and keep a site or a workspace off. Every entry links to the report form.
• Each change is in the workspace’s audit log as site.showcase.

Password-protected sites#

A password site asks every reader for one password before it opens: no account, no sign-in, nothing to set up for the people you send it to. Give them the link and the password, by whatever channel suits. It is the level for a client review or a draft for people outside the workspace, when asking each of them to sign in would be too much and an open link too little.

Choose Password under Access on the site’s page and type it there, or set it from an agent: visibility=password with password on publish or PATCH, the same pair on the MCP publish and set_visibility tools, or colophon visibility <site> password, which asks for it in the terminal (or reads --password-stdin) rather than taking it as an argument. It must be at least six characters.

• The reader types it once, at the dashboard’s gate, and the page stays open in that browser for an hour, through the same signed, host-only cookie a restricted site’s reader gets.
• Only a salted, slow hash is stored. Nothing shows the password again — not the dashboard, the API or the MCP tools — so keep it where you keep the link. To change it, set a new one: everyone holding the old one is asked again on their next click.
• Moving the site to another level discards the password. Coming back to password asks for one again.
• Ten wrong tries in fifteen minutes from one address (an IPv6 one by its /64) hold the gate for that address until the window rolls. A hundred wrong tries in an hour, from anyone, close it to everyone until the hour rolls: the log says when, and setting a new password opens it at once. Each try, right or wrong, is in the workspace’s audit log; what was typed never is.
• Workspace members are asked too: the password opens the site, not an account. An agent with a key, or a member reading through the API or read_site, is already past the gate.
• Like unlisted, it is never indexed, carries no footer, and its traffic is counted anonymously. Nobody signs in, so there are no named readers and no comments.

Sharing a restricted site#

On the site’s page, add an address under Shared with. The person does not need an account: when they open the link they are asked to sign in, and if the address they sign in with is on the list, they are let through. Google, GitHub, Microsoft and emailed links all work — what matters is the verified address, not the provider. A workspace with its own identity provider can let readers at its domains use that too: Single sign-on.

Removing an address takes effect on their next click, not when some token expires. Workspace members can always open restricted and private sites without being listed.

Everyone at a company#

Add @acme.com under Shared with instead of an address, or pass it to the MCP share_site tool, and anyone who signs in with an address at acme.com is let through: the people you name and the ones you don’t know about yet, new starters included.

• The domain has to match exactly. @acme.com does not let in eng.acme.com; add that as its own entry.
• Only an address the sign-in provider vouched for counts. An account whose address was never verified passes no domain entry, whichever way it signed in.
• Mail anyone can sign up for — @gmail.com, @outlook.com, @icloud.com, @proton.me and the like — is refused as a domain, since it would open the site to most of the internet. Add people there by their own address.
• Nobody is mailed when you add a domain, because there is no one address to send the link to. Send it to the people there yourself.
• It takes Can view or Can comment like an address, and removing it takes effect on everyone’s next click. If someone is on the list by address too, they get whichever of the two allows more.
• It never takes Can approve: an approver makes versions live, so name the people who sign off by their own addresses (below).

Comments#

Each address on the list is Can view, Can comment or Can approve; set it on the site’s page, or pass role to the MCP share_site tool. People who can comment or approve, and workspace members from Commenter up, see a Comments button on the page. They select any text and press Comment, and the comment panel opens beside the page, where they write; the comment is pinned to that passage, which stays marked on the page. Others reply under it, and whoever deals with it resolves it.

The panel is a page of Colophon’s own site, shown inside the page as a sheet down its side, or along its foot on a phone. What reviewers write, and every Post, Resolve and Reopen, happens there and not in the page, because the page’s own scripts could send anything the page itself sent as the person reading it: a version in review could resolve its reviewers’ comments, or answer “Looks good” for them. For the same reason, the panel takes a press only while the browser can confirm nothing on the page covers or fades it. Safari and Firefox cannot confirm it, and a site on its own domain cannot show it inside the page signed in, so there the panel opens in a window of its own, beside the page; selecting text on the page still starts a comment in it.

Comments exist on restricted and private sites only. A public, unlisted or password page shows no comment tools to anyone, so nobody with the link can write on it. On a private site only members comment, since its list admits nobody. When a later publish changes the page, its threads stay and are marked outdated; they still take replies. The agent that published the page can read them and answer through the API or the MCP tools list_comments and answer_comment, and the workspace’s notification channel hears about each new one.

Outside approvers#

Can approve is the third level on a restricted site’s list, above Can comment and including it. It is for one person outside the workspace, by their own address: the client signing off on the proposal. Choose it under Shared with, or pass role: "approver" to the MCP share_site tool. Only owners grant it, as with all sharing, and never to a domain.

When a version is sent for review, each approver is mailed a link to the page. It goes through the gate, so they sign in as that address, and it always opens whichever version is in review, even after a newer one replaced the one they were mailed about: it sends them on to that version’s preview, on its own host, where the gate lets them in again without asking, since they are signed in already. On the page, the Review button opens the panel with the version and the note it was sent with (so write that note for them too), and Approve or request changes takes them to a page on Colophon’s own site. There they write a note of their own and choose Approve and make live or Request changes. Either takes the note. They never see the workspace’s dashboard, other versions or other sites.

The decision is made there, not on the page, because the page is the version being decided on: its own scripts run beside anything Colophon adds to it, so anything sent from the page, they could send too. A version could approve itself the moment its approver opened it.

• One approval is enough, theirs or a publisher’s. Theirs is the same as a publisher’s in every way but who gave it: the version goes live, the person who sent it is mailed, the channel hears it, and the review, the audit log and the notices all name them as an outside approver.
• A decision is about the version they read. If a newer one was sent since, it is refused and names the one in review now; one that was decided already is refused too.
• Only an address a sign-in provider vouched for can decide, and only while the site is restricted: on a public, unlisted, password or private site the level does nothing. A workspace member on the list decides by their workspace role, in the dashboard, not by the list.
• Lowering them to Can comment or removing them takes effect on their next click, whatever their page still shows.

Who opened it#

A restricted or private site shows its owners and publishers who has opened it, under Opened by on the site’s page: each person, how many visits (views within 30 minutes count as one), when they last came (to the minute), whether that was the version live now, an earlier one or the one in review, and how long they have read and how far down they got (time on page and scroll depth). Below it, everyone the site was shared with who has not opened it yet; a domain stays there for good, since nobody can list everyone at a company, with a count of the people there who have. The names come from the sign-in a reader passes to open the page, and the mail that shares a site says so. Public, unlisted and password sites have no names to give; their traffic counts stay anonymous and are never joined to anyone. An agent reads the same list through GET /api/v1/sites/:id/readers, or in get_site over MCP.

The first time someone opens the site, and the first time they open a version they had not seen — a new live version, or the one sent for review — whoever published the live version and whoever asked for the review are mailed, by name and version, with a link to Opened by. When neither of them may see who opened it, the owners are. Opens a few minutes apart come as one mail, and nobody is mailed twice about the same person and version. The workspace’s notification channel hears it too, except when the people mailed open the site themselves. Each person turns these mails off, or on for a site they did not publish, on the site’s page, and off for every site under Notifications; an agent acting for them does the same through the API or the MCP tool set_read_alerts. Public, unlisted and password sites name nobody, so they announce nobody.

What happens on a restricted link#

1. The visitor opens https://acme.usercontent.colophon.fyi/board-deck/.
2. With no proof of identity for this workspace, they are redirected to the dashboard’s sign-in gate.
3. After sign-in, the gate checks their email against the site’s list and workspace membership.
4. If allowed, they are sent back to the hostname they opened — the subdomain, or the workspace’s own domain — with a short-lived, signed grant cookie scoped to that origin. It lasts an hour; renewing it is a silent redirect.
5. If refused, they see a “you don’t have access” page and the workspace owner is emailed that someone asked.

Choosing a level#

• A report for a colleague who will open it on their phone in a hurry: unlisted.
• Something you want found: public.
• A draft for a client who has no account and should not need one: password, and send the password separately.
• Board material for named people outside the team: restricted, and add their addresses.
• A proposal for a client’s whole team: restricted, and add @client.com.
• Internal notes: private.

Restricted and private mean the reader signs in first, so use them when access control actually matters, not by default. See also Workspaces, members & keys.