diff --git a/dashboard/roles.mdx b/dashboard/roles.mdx index 554541f8f..29c800848 100644 --- a/dashboard/roles.mdx +++ b/dashboard/roles.mdx @@ -49,6 +49,67 @@ Mintlify provides three dashboard access levels: viewer, editor, and admin. With Limit admin access to only the people who need to perform admin tasks. +On Enterprise plans, you can also see what each role can do in the **Role permissions** section of the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard. + +## Expanded roles + +If the role picker on your **Members** page offers **Publisher** and **Commenter**, your organization uses six roles instead of three: owner, admin, publisher, editor, commenter, and viewer. The **Role permissions** section shows a column for each. + +When your organization switches to expanded roles, existing editors become publishers so they can still publish. Members whose role comes from your identity provider keep their assigned role. Each organization has one owner. + +- **Owner**: Everything an admin can do, plus deleting the project, deleting the organization, and transferring ownership. +- **Admin**: Full control over content, members, roles, and settings, including billing and the custom domain. +- **Publisher**: Everything an editor can do, plus publishing to the live site and approving reviews. +- **Editor**: Create and edit content, request reviews, and manage site and workspace settings, integrations, API keys, and the assistant. Can't publish to the live site or approve reviews. +- **Commenter**: View and comment on content. Can't edit content. +- **Viewer**: View content and preview unpublished edits. + +| | Viewer | Commenter | Editor | Publisher | Admin | Owner | +| ---------------------------- | :----: | :-------: | :----: | :-------: | :---: | :---: | +| View pages | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Preview unpublished edits | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Comment on pages | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | +| Create and edit pages | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| Reorganize pages | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| Delete pages | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| Request review | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| Review changes | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| Publish to the live site | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| Manage site and workspace settings | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| Invite and remove members | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| Assign roles | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| Manage page access | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| Manage custom roles | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| Manage custom domain | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| Manage billing and plan | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | +| Delete the project | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | +| Delete the organization | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | +| Transfer ownership | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | + +You can only invite members or assign roles up to your own role. + +## Custom roles + +In organizations that use [expanded roles](#expanded-roles), admins and owners can create custom roles with exactly the permissions a team needs. Custom roles appear in the **Custom roles** section of the [Members](https://app.mintlify.com/settings/organization/members) page. + +### Create a custom role + +1. Navigate to the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard. +2. In the **Custom roles** section, click **New custom role**. You can also select **Create custom role** from a member's or an invite's **Role** dropdown. +3. Enter a **Label**, which appears in role menus, and an optional **Description** to help admins pick the right role. +4. In the permissions table, choose a level for each area. Content areas, such as pages, comments, and publishing, use **Read** and **Write**. Project and organization areas use **View** and **Manage**. +5. Click **Create role**. + +You can only grant permissions that you have yourself. Each custom role needs a unique name. + +### Change or delete a custom role + +1. In the **Custom roles** section, open the role's actions menu. +2. To change the role, select **Manage role**, edit its label, description, or permissions, and click **Save**. +3. To delete the role, select **Delete role**, then click **Delete permanently**. + +Deleting a custom role cannot be undone. You can't delete a role that is still assigned to members or SSO groups. Reassign them first. + ## Repository contributors and deployments Anyone with write access to your documentation repository can contribute by pushing changes. Pushes to your deploy branch deploy automatically, whatever the person's dashboard role. Dashboard roles only control what people can do in the Mintlify dashboard. @@ -77,6 +138,19 @@ Admins can change the role assigned to any member. The new role takes effect the next time the member loads the dashboard. You can't change your own role. If a member's role comes from [SCIM directory sync](/dashboard/scim#roles-for-provisioned-members), their row shows **Managed by SSO**, and you change their role in your identity provider. +If your organization uses [expanded roles](#expanded-roles), the owner's row shows **Owner**. The owner's role changes only when the owner transfers ownership to another member. + +### Transfer ownership + +If your organization uses [expanded roles](#expanded-roles), the owner can make another member the owner. You become an admin, and only the new owner can transfer ownership back. + +1. Navigate to the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard. +2. In the member's row, select **Owner** from the **Role** dropdown. +3. In the **Transfer ownership?** dialog, type `TRANSFER` to confirm. +4. Click **Transfer ownership**. + +You can only transfer ownership to an active member. You can't transfer it to a pending invite or to a member whose role comes from your identity provider. + ## Remove a member Admins can remove a member from the organization entirely, which deletes their access and any keys they created. @@ -85,6 +159,8 @@ Admins can remove a member from the organization entirely, which deletes their a 2. In the member's row, open the actions menu and select **Remove member**. 3. Click **Remove** to confirm. +You can't remove the owner of an organization that uses [expanded roles](#expanded-roles). To remove them, [transfer ownership](#transfer-ownership) to another member first. + Removing a member deletes the member from your organization. Revoking a member's credentials signs them out and clears their keys, but keeps their membership. ## Revoke a member's credentials @@ -107,4 +183,4 @@ You can revoke any combination of the following credentials: | M2M clients | Revokes the member's machine-to-machine client credentials. | | Connected apps | Disconnects the apps the member authorized through OAuth. | -Revoking credentials cannot be undone. The member can sign in again and create new keys and tokens unless you also remove them from the organization or block their sign-in method. You cannot revoke your own credentials. +Revoking credentials cannot be undone. The member can sign in again and create new keys and tokens unless you also remove them from the organization or block their sign-in method. You cannot revoke your own credentials or the owner's credentials. diff --git a/editor/collaborate.mdx b/editor/collaborate.mdx index 5a107753e..4cbca075a 100644 --- a/editor/collaborate.mdx +++ b/editor/collaborate.mdx @@ -10,7 +10,7 @@ Work with your team on a page by commenting on it, suggesting changes to it, or ## Comments - All [roles](/dashboard/roles) can comment, reply, and resolve threads. + All [roles](/dashboard/roles) can comment, reply, and resolve threads. If your organization uses [expanded roles](/dashboard/roles#expanded-roles), commenters and higher roles can comment, but viewers can't. Comments let you leave feedback on specific text or on a whole page without editing the content. diff --git a/mint-instructions/access/team.mdx b/mint-instructions/access/team.mdx index e731ab5af..edfdb7529 100644 --- a/mint-instructions/access/team.mdx +++ b/mint-instructions/access/team.mdx @@ -18,8 +18,9 @@ Use this to add teammates, set roles, SSO, SCIM, session or IP policies, audit l - Viewer: view editor content, dashboard and analytics, ask the Slack agent questions, comment. Always in suggesting mode in the editor; cannot accept suggestions. - Editor: everything a viewer can, plus edit in the web editor, publish, create/rename/delete pages, reorder navigation, upload media, trigger, roll back and promote deployments, create/delete API keys, configure integrations, assistant and add-ons, make changes with the Slack agent, accept or reject suggestions, invite editors and viewers. - Admin: everything, plus update roles, invite admins, delete users, billing, SSO, SCIM, IP allowlist and session lifetimes, audit logs, security contact, custom domain, Git source, custom subpath, delete a project, agent publishing setting, delete organization, delete any comment. - - Change a role: **Members** page, **Role** dropdown (saves immediately, applies on next dashboard load). You cannot change your own role. **Managed by SSO** rows change in the IdP. -4. Offboard: **Members** page, actions menu. **Remove member** deletes membership, access and their keys. **Revoke credentials** keeps membership and revokes any of: Sessions, CLI tokens, API keys, Discovery API keys, M2M clients, Connected apps. Not reversible; you cannot revoke your own. + - Expanded roles: if the **Members** role picker offers **Publisher** and **Commenter**, the org has six roles: viewer, commenter, editor, publisher, admin, owner. On the switch, existing editors became publishers (IdP-managed roles unchanged), and each org has one owner. Viewer: view and preview only, cannot comment. Commenter: view and comment, cannot edit. Editor: create, edit, reorganize, and delete pages, comment, request review, and manage site and workspace settings, integrations, API keys and the assistant. Cannot publish or approve reviews. Publisher: editor plus publish and approve reviews. Admin: plus members, roles, page access, custom domain, billing. Owner: admin plus delete the project and the organization, and transfer ownership. Members can only invite or assign roles up to their own. **Role permissions** on the **Members** page (Enterprise) shows each role's permissions. Custom roles (expanded roles, admins and owners): **Members** page, **Custom roles**, **New custom role** (or **Create custom role** in a **Role** dropdown), set **Label**, optional **Description**, and per-area levels (content: Read/Write; project and organization: View/Manage), **Create role**. You can only grant permissions you have. **Manage role** edits; **Delete role** then **Delete permanently** (fails while assigned to members or SSO groups). + - Change a role: **Members** page, **Role** dropdown (saves immediately, applies on next dashboard load). You cannot change your own role. The owner's role changes only by transfer: the owner selects **Owner** in another active, non-SSO-managed member's **Role** dropdown, types `TRANSFER`, clicks **Transfer ownership**; they become admin. **Managed by SSO** rows change in the IdP. +4. Offboard: **Members** page, actions menu. **Remove member** deletes membership, access and their keys. **Revoke credentials** keeps membership and revokes any of: Sessions, CLI tokens, API keys, Discovery API keys, M2M clients, Connected apps. Not reversible; you cannot revoke your own. With expanded roles, you cannot remove the owner (transfer ownership first) or revoke their credentials. 5. SSO (Enterprise, admin): **Security** page (https://app.mintlify.com/settings/organization/access), **SSO** section. Each button opens the Admin Portal, which has the identity provider steps. - First **Verify email domains**: add your team's email domain and its DNS record in the Admin Portal. **Set up SSO** stays disabled until a domain shows **Verified**. - Then **Set up SSO** and follow the Admin Portal steps. When connected, the section shows **SAML SSO** with a **Connected** badge. **Manage SSO** reopens the portal.