# Documents and access

> What a document holds, who may do what in it, and how people get into the editor.

A **document** is one piece of writing and its whole record: the text, its images, comments and suggestions, who wrote each word, and the seals made from it. Proof stores all of that. Your product decides who can reach which document, and Proof enforces it in the editor and for agents.

## What Proof keeps and what you keep

Proof keeps what has to be on the record, and nothing about how your product is organised.

| Proof keeps | You keep |
| --- | --- |
| The text, images, comments and suggestions | Folders, pins, favourites and ordering |
| The document's name | Your document list and search screens |
| Members, their roles, and link access | Invitations, share dialogs and emails |
| Who wrote what, presence and check-ins | Notifications (Proof sends you [events](/reference/webhooks/)) |
| Seals | Anything else your product shows around the editor |

`GET /v1/users/{user_id}/documents` lists the documents a user is a member of, most recently edited first. Most platforms show that list with their own folders and pins laid over it, keyed by document id.

## Names and titles

A document's **name** is set by an editor, in the editor or with `PATCH /v1/documents/{id}`. Its **title** is what to show: the name if it has one, otherwise the document's first line. Show `title` in your lists and it stays right as people write.

## Roles

Each member has one role. Proof checks it on every change, in the editor and over MCP.

| Role | May |
| --- | --- |
| `owner` | Everything an editor may, and seal, withdraw seals, choose who reads its seals, trash and delete. A document has one or more owners, and always at least one. |
| `editor` | Write, rename, accept and reject suggestions, comment. |
| `suggester` | Propose changes as suggestions, and comment. Their edits never change the text until an editor accepts them. |
| `viewer` | Read, and see comments. |

You set roles with `PUT /v1/documents/{id}/members/{user_id}`. Setting someone's role to `owner` makes them an owner too; to hand a document over, then lower the old owner's role. Lowering or removing the last owner is refused. A role change reaches open editors at once: someone made a viewer reloads unable to type, and someone removed sees the document close.

Agents act with at most `editor`, never `owner`, and never more than their person's current role. See [Agents](/concepts/agents/).

## Link access

A document can also be open to anyone you send through its link. `link_access` is one of:

| Value | People who come by link get |
| --- | --- |
| `restricted` | Nothing. Only members can open it. This is the default. |
| `view` | `viewer` |
| `suggest` | `suggester` |
| `edit` | `editor` |

Proof doesn't know your document URLs, so "came by link" is your call: when someone who isn't a member opens your page for a document, start their session with `via: "link"`. They get the link's role, or are refused if access is `restricted`. A member always gets the higher of their own role and the link's.

People who come by link are still users. Give them an id and a name first, even a made-up one for someone signed out; see [Anonymous users](/guides/anonymous-users/).

## Sessions are the only way in

Nobody opens a document in the editor without a **session**: a token your server asks for with `POST /v1/sessions`, naming one user and one document. Proof works out the user's role when it issues the token and refuses one for a user who may not open the document. The token lasts 15 minutes; the embedded editor asks your page for a new one before it lapses, so your server can refuse when access has ended.

Because a session is for one user and one document, a token that leaks from a page reaches only that document, as that person, for a few minutes. See [Embed the editor](/guides/embed-the-editor/).

## Trash and deletion

- **Trash.** An owner, or their agent, can move a document to the trash for everyone. It disappears from everyone's lists, agents can't reach it, its seals are down, and only its owners can still open it, to read. `POST /v1/documents/{id}/restore` brings it back. After 30 days in the trash it is deleted. Another member who trashes it puts it in their own trash: it leaves only their list, and after 30 days they leave the document.
- **Delete.** `DELETE /v1/documents/{id}` deletes it for everyone at once, agents included. Open editors close, its images are deleted, and its seals are withdrawn: their pages say so.

Deleting can't be undone. Proof sends `document.trashed`, `document.restored` and `document.deleted` events for trashing for everyone, restoring and deleting, so your lists stay in step when an agent does it.

## Images

People drop or paste images into the text. Proof resizes each to fit 1.9 MB in the browser, stores up to 100 MB of images per document, and serves them only to people who may open the document. Deleting the document deletes them.

## Related

- [Share documents](/guides/share-documents/)
- [Documents reference](/reference/api/documents/) and [Members reference](/reference/api/members/)
- [Sessions reference](/reference/api/sessions/)