Access and sharing

Who can read, edit and manage a document or use a template — people, groups, API keys and embed sessions.

Every document has an owner and is private by default. Access is granted explicitly, and the same rules apply everywhere: the app, the REST API, MCP, the collaborative editor and embed sessions.

Levels

Level	Allows
`read`	Content, form, attachments, findings, summary and export (as the export policy allows).
`edit`	Everything in `read`, plus changing content and form, attachments, generation and status.
`manage`	Everything in `edit`, plus sharing, transferring ownership and deleting.

Who has which level

Principal	Level on a document
Owner — the person or API key that created it	`manage`
Organization admin	`manage` on every document of the organization (audited)
Shared with a person, or with a group they belong to	`read` or `edit` — grants add up, `edit` wins
API key with document scope `organization`	`read`, or `manage` with edit permission
API key with document scope `selected`	The level an admin granted it on that document
Embed session	The issuing key's level on its one document, capped by the session `mode`; never `manage`
Anyone else, or anyone who left the organization	Nothing — the document reads as not found

Access is checked live on every request. Removing a share, a group membership or an organization membership takes effect immediately, including on editors that are already open: they switch to read-only or close.

The owner or an admin shares from the document's Compartir dialog, over REST or over MCP:

curl

curl -X PUT "https://thedocdealer.com/api/documents/$DOC/shares" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"subjectType": "group", "subjectId": "<groupId>", "level": "edit"}'

GET /api/documents/{documentId}/shares lists the owner and the shares; DELETE …/shares?subjectType=user&subjectId=… removes one. Sharing with people and groups is done by people. API keys are given documents by admins, from the key's settings (see document scope).

Groups

Admins create groups and designate managers; managers add and remove members of their groups without approval. Groups receive document shares and template access. They are managed in /groups (members and managers) and /admin/groups (admins), or over MCP (list_groups, create_group, add_group_member, …).

Ownership

POST /api/documents/{documentId}/transfer with { "toUserId" } or { "toApiKeyId" } hands a document to another member or key of the organization; shares are kept. A person who owns documents cannot be removed from the organization in DocDealer until their documents are transferred, and an API key that owns documents cannot be deleted (disable it instead). Documents of someone removed directly from your identity provider stay available to admins until they are transferred.

Templates

Templates are admin-only until access is granted. An admin grants a person, a group or the whole organization the right to use a template — see it and create documents from it. Editing a template is always reserved to organization admins.

Template access and document access are independent: being able to use a template never shows you the documents others created from it, and a document shared with you does not give you its template. An API key uses the templates of its template allowlist.

What your integration should do

Create documents with your API key: your integration owns them and keeps reaching them with document scope own.
Give a key selected or organization scope only when it must reach documents people create in DocDealer.
Put your end users in front of a document with an embed session, in read or edit mode, naming them with externalUserId and displayName for attribution.