---
name: link-permissions
description: The link_permission tier — what an anonymous URL-holder can do on a share.
---

# Link permissions

Every share carries two independent access dimensions:

1. **Visibility** — who can read the share (`public` / `unlisted` / `members`). See [Visibility and passwords](/docs/visibility).
2. **Link permission** — what an anonymous URL-holder can do *beyond* reading. Set per share, independent of visibility.

If you've used Google Docs, link permissions are the "anyone with the link can comment" tier: a unilateral grant attached to the URL, separate from the explicit member roster.

## The four tiers

| tier | What URL-holders can do |
| ---- | ----------------------- |
| `none` (default) | Read only, subject to visibility. |
| `can_view` | Same as `none` today — reserved for a future "Shared with you" pill in the renderer. |
| `can_comment` | Post comments and react with emoji without being explicitly added to the share. |
| `can_suggest` | Submit suggested changes (rate-limited; lands in the owner's suggestions inbox). |

Each tier additively unlocks the next — `can_suggest` includes commenting; `can_comment` includes viewing.

## When to use each tier

- **`none`** — the default. Recipients can only read. Comments and suggestions require explicit membership.
- **`can_comment`** — sending a draft to a client and you want their feedback on the page itself instead of by email. Pair with `unlisted` visibility for the "URL-only" sweet spot.
- **`can_suggest`** — long-form documents (proposals, contracts, RFCs) where you want the recipient to mark up exact lines rather than describe changes in prose. The recipient submits a full proposed new version; you approve or reject from the [suggestions inbox](/docs/suggestions).
- **`can_view`** — reserved. Same effect as `none` today; sets up a "Shared with you" recipient affordance for a future release.

## Matrix vs visibility

Link permission stacks on top of visibility — it widens *what* URL-holders can do, never *who* gets access.

| Visibility | `link_permission` | Effect on an anonymous URL-holder |
| ---------- | ----------------- | --------------------------------- |
| `public` | `none` | Reads. Comments/reactions require sign-in. |
| `public` | `can_comment` | Reads. Posts comments + reactions without sign-in. |
| `unlisted` | `none` | Reads if they have the URL. |
| `unlisted` | `can_comment` | Reads + comments without sign-in. |
| `unlisted` | `can_suggest` | Reads + comments + submits suggestions. |
| `members` | `none` | Anonymous → 404 (membership is the only gate). |
| `members` | `can_comment` | Anonymous → 404 still; members get comment access through their membership. |

`members` + `can_comment`/`can_suggest` is allowed but mostly a no-op for anonymous visitors — they don't pass the membership gate in the first place. Use the link-permission tier on `unlisted` shares; that's where it does real work.

## Setting the tier

### Web

Open the share's settings page (`Dashboard` → share row → `⋯` → `Share & permissions`). The "Link permission" row at the top has the four tiers as radio buttons. Picking a new tier saves immediately.

### API

```bash
curl -sX POST https://anchorify.io/api/v1/shares/<id>/link-permission \
  -H "Authorization: Bearer $REPO_SHARE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"link_permission":"can_comment"}'
```

See [`POST /api/v1/shares/:id/link-permission`](/docs/api#post-apiv1sharesidlink-permission--set-the-link-permission-tier) for the full surface.

## Rate limiting

Anonymous comments and suggestions go through the same per-IP token bucket as authenticated writes. A flood of comments or suggestions from one IP gets `429`d well before it threatens to spam the share. See [Rate limits](/docs/api#rate-limits).

## What's not in here

- **Per-recipient link permissions** — every URL-holder gets the same tier today. "This recipient can comment, that recipient can only view" requires explicit member grants (see [Doc-level roles](/docs/doc-roles)).
- **Time-limited links** — link permissions don't expire. The tier persists until you flip it back.
- **Anonymous-suggester captcha + rate limit hardening** — V4 #20, not yet shipped.