Workspaces, members & keys

A workspace is the unit of isolation: its own subdomain — or a domain of your own — members, API keys, sites and limits. You can belong to several and switch between them from the sidebar.

The workspace

Your first sign-in creates one. Its subdomain is permanent — every site URL is built from it, and changing it would break every link ever handed out. Thedisplay name is yours to change under Members → Workspace.

More than one

One workspace per client, team or project: under Account → Workspaces (or New workspace in the sidebar switcher) give it a name and it is created with you as its owner and made current. The subdomain comes from the name — Acme Corp becomesacme-corp, with a short suffix if that is taken — and, as always, never changes. Invite the client’s people to that workspace and nothing else of yours is visible to them; your one sign-in switches between all of them.

Each person may create a few workspaces (the number is shown on the account page). Need more? Write to us with what they are for and the limit is raised for you. Workspaces you were invited to do not count, and neither does one you have transferred to someone else.

Isolation is enforced in the database with row-level security on every tenant table, not by the application remembering to filter. Serving also gives each workspace its own origin, so the browser keeps tenants apart too.

Your own domain

A workspace can answer on one hostname it controls — https://sites.example.com/<slug>/instead of https://acme.usercontent.colophon.fyi/<slug>/. An owner attaches it under Members → Workspace and gets two DNS records to add:

The page shows Waiting for DNS until both resolve, re-checking every few minutes, then Live. From that moment every site also answers at the new hostname, the API and the dashboard hand out that URL, and nothing needs republishing. The subdomain keeps working beside it; restricted and private sites sign people in exactly as before; short links move over too. If a record later disappears, URLs fall back to the subdomain until it returns.

One hostname per workspace; Remove frees it at once. A root domain (example.com) works when your DNS provider can point it at a hostname — CNAME flattening or an ALIAS record — because the check only asks that it resolve to the same place the subdomain does. Until both records are in place, a hostname you have typed is held for your workspace but not served: nobody else can claim it, and no link points at it.

A site’s own domain

A hostname can also name one site rather than the workspace: https://docs.example.com/for the site published as docs, with the site at the root and nothing else of the workspace answering there. Attach it from the site’s page, or withcolophon publish --domain docs.example.com; the two records are the same as above — the CNAME still points at your workspace subdomain — and the flow is identical: claimed at once, served and handed out only once both records hold, the /docs/path under the subdomain kept working beside it. One hostname per site, and a hostname belongs to either one site or one workspace, never both. Since the site owns the root of its hostname, /l/…, /e, /api/… and paths starting with_ are reserved there, as on every hostname.

Members and roles

One owner is the primary owner: they cannot be removed or demoted. To hand that protection to someone else, use Transfer ownership and type the workspace name to confirm; you keep the owner role, only the protection moves. A workspace always keeps at least one owner.

Inviting people

Under Members, enter an address and a role. We email them a link straight away. Opening it asks them to sign in as that address — only the address named on the invitation can accept it — and then to accept, which is what adds the workspace to their switcher. Signing in on its own never joins anything, so someone who already has an account does not have to sign out and back in. Invitations expire after 14 days and can be cancelled before then; re-inviting the same address sends a fresh link and retires the old one.

API keys

A key is what an agent holds. It authenticates as the workspace, never as a person, and every use is recorded against it in the audit log. Create keys under API keys or with colophon create-token; the plaintext is shown once and only its hash is stored.

Revoking a key takes effect on the next request. Name keys after the agent that holds them so the audit log reads well later.

Signed-in machines

colophon login gives a machine a session rather than a key: it acts as you, in whichever workspace you choose, and can do what your role allows — including minting keys if you are an owner. Sessions last 30 days from their last use. Every signed-in machine is listed under Account → CLI sessions with when it was last used, and any of them can be revoked there; the next command on that machine fails and asks for a fresh login.

Limits

Per workspace, on the free plan:

Hitting a limit returns 429 with a message naming it. The 24-hour caps exist to blunt abuse from throwaway accounts; they lift on their own. Higher limits can be set per workspace — write to us with what you need.