# Sharing & access control · Comma Docs

Canonical: https://commareports.com/docs/sharing

> Comma's report access model: five visibility levels, link permissions, per-person roles, password-protected and expiring links, domain-gated viewing, and zero-knowledge encryption.

# Sharing & access control

Every report has one owner, a visibility level, and a link permission. The
combination answers the two questions that matter: *who can open it* and
*what can they do once it's open*. All of it is enforced server-side — the
same rules apply whether the report is opened in a browser, fetched over
the REST API, or read by an agent through MCP.

## Visibility: who can open it

| Level        | Who can open the report                                          |
| ------------ | ----------------------------------------------------------------- |
| `private`    | Only the owner and people explicitly invited.                     |
| `team`       | Members of the report's team.                                     |
| `domain`     | Anyone signed in with an email on your company domain (Enterprise). |
| `registered` | Any signed-in Comma user with the link.                           |
| `public`     | Anyone with the link, no account needed.                          |

## Link permission: what the link grants

For reports that are reachable by link, the link itself carries a
permission: `view` (read only), `comment` (read + leave anchored comments),
`edit` (full collaboration), or `none` (the link alone grants nothing —
access must come from an invite, team membership, or domain match).

## Per-person roles

Independent of the link, you can grant individuals a role on a report:
**owner**, **admin**, **editor**, **commenter**, or **viewer**. Roles win
over the link — a teammate invited as editor can edit even when the link is
view-only.

## Extra gates

- **Password-protected links** *(Enterprise)* — set or clear a password on
  the share link; the password is required in addition to the link.
- **Expiring links** *(Enterprise)* — links that stop working on a date you
  choose.
- **Domain-gated viewing** *(Enterprise)* — `domain` visibility checks the
  viewer's verified email domain server-side; no per-viewer invites, no
  viewer seats to buy. Pairs with [SSO/SAML and SCIM](/security) for teams
  on an identity provider.

## Setting access from the API or an agent

The share state is readable with `reports:read` and writable with the
dedicated `sharing` scope — so a publishing token can't silently widen
access:

```bash
curl -X PUT https://commareports.com/api/v1/reports/REPORT_ID/share \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "team", "public_permission": "none" }'
```

Agents do the same through the MCP tool `set_report_sharing`.

## When the content itself is sensitive

Zero-knowledge encrypted reports encrypt in your browser with a key derived
from your passphrase; the server stores only ciphertext. The tradeoff is
deliberate: encrypted reports can't be link-shared, scheduled, or sent to
team destinations — the server can't read them, so it can't serve them to
anyone but you. See [Security →](/security).

## Defaults worth knowing

- Reports created over the API start `private` unless the create call says
  otherwise; `team` and `domain` are set after creation via the share
  endpoint, which carries the side data they need.
- Viewers are never charged for and never need a paid seat — pricing is per
  publisher, not per reader. See [Pricing →](/pricing).