---
name: doc-roles
description: Doc-level roles — org admins, project members, share editors, and org viewers.
---

# Doc-level roles

Anchorify has four named roles you can grant a user. They differ in scope (one share / one project / one org) and in capabilities (read / read+write).

| Role | Scope | Capabilities | Granted via |
| ---- | ----- | ------------ | ----------- |
| **Org admin** | Every project and share in the org | Read, edit, publish, delete, member management | `org_members` (one per user — your home org) |
| **Project editor** | All shares in one project | Read, edit, publish, delete inside that project | `project_members` row with `role='editor'` |
| **Project viewer** | All shares in one project | Read only | `project_members` row with `role='viewer'` |
| **Share editor** | One specific share | Read, edit, flip visibility on that share | `share_members` |
| **Org viewer** | Every project and share in the org | Read only (no edit, no publish) | `org_viewers` |

Each user has exactly one "home" org where they're an admin (created automatically on signup). Additional roles in other orgs come from invites + grants.

## Choosing a role

- **Org admin** — for someone joining your team as a peer. They get full write access to everything in the org.
- **Project editor** — a teammate working on one project (e.g. one client) who shouldn't see your other client work.
- **Project viewer** — a client who needs to read everything in their project but should never publish or edit.
- **Share editor** — narrow case: one specific deliverable you want a collaborator to edit, without exposing the rest of the project.
- **Org viewer** — a stakeholder (a boss, an auditor, an investor) who needs read access to everything but should never be confused with a peer admin.

If unsure: prefer the narrower role. You can always widen later by removing the old grant and adding the wider one.

## Granting a role

Grants only work for users who already have a Anchorify account. For users without an account, use the [invite flow](/docs/invites) — they accept via magic link and the role materializes after they pick a username.

### Web

| Role | Where |
| ---- | ----- |
| Org admin | `Dashboard` → `Settings` → `Members` → **Invite admin** |
| Project editor / viewer | Project page → `Settings` → **Add member** (pick role from dropdown) |
| Share editor | Share row `⋯` → **Share & permissions** → **Add an editor** |
| Org viewer | `Dashboard` → `Settings` → `Members` → **Add org viewer** |

### API

| Role | Endpoint |
| ---- | -------- |
| Org admin | [`POST /api/v1/orgs/:slug/members`](/docs/api#post-apiv1orgsslugmembers--add-an-org-admin) |
| Project editor / viewer | [`POST /api/v1/orgs/:slug/projects/:pslug/members`](/docs/api#post-apiv1orgsslugprojectspslugmembers--add-a-project-member) (`role:` field) |
| Share editor | [`POST /api/v1/shares/:id/members`](/docs/api#post-apiv1sharesidmembers--grant-share-editor-access) |
| Org viewer | [`POST /api/v1/orgs/:slug/viewers`](/docs/api#post-apiv1orgsslugviewers--grant-org-wide-viewer-access) |

All four require the caller to be an org admin of the relevant org. Notification of the grant fires automatically (`member.added_to_org` / `member.added_to_project` / `member.added_to_share`).

## Revoking a role

Every grant has a matching `DELETE` endpoint and a **Remove** button on the share-settings / project-members / members pages. Removing a grant is immediate — the user loses access on their next request.

The one constraint: an org admin cannot remove themselves. Ask another admin to remove you, or use the org-merge flow if you're the sole admin trying to leave.

## Role precedence

When a user holds multiple roles on the same share (e.g. they're both a project viewer and a share editor), the **widest applicable role** wins:

- Org admin > Project editor > Share editor > Project viewer > Org viewer > link-permission tier.

Practical consequence: granting a project viewer share-editor access on one specific share doesn't downgrade their viewer access on the rest of the project. Add roles freely; the permission system always picks the maximum.

## How this stacks with link permissions

The [`link_permission`](/docs/link-permissions) tier of a share is a separate, additive grant for anonymous URL-holders. It never narrows what an explicitly-granted member can do. A project viewer can always read; a share with `link_permission='can_comment'` lets URL-holders comment too — but doesn't widen the viewer's role.

## What's not in here

- **Custom roles** — the five named roles are the whole model. No "almost-admin" or "publish-but-not-delete" today.
- **Per-resource-type permissions** — you can't say "this user can edit shares but not invite new viewers."
- **Time-bound roles** — grants don't expire. Remove when no longer needed.