Refinements

Author: SarahSoutoul

docs/guides/billing/for-b2b.mdx

@@ -50,7 +50,8 @@ You can create a pricing page by using the [`<PricingTable />`](/docs/reference/
 
 You can use Clerk's features, plans, and permissions to gate access to content using [**authorization checks**](/docs/guides/secure/authorization-checks). There are a few ways to do this, but the recommended approach is to either use the [`has()`](/docs/reference/backend/types/auth-object#has) method or the [`<Protect>`](/docs/reference/components/control/protect) component.
 
-Permission-based authorization checks link with feature-based authorization checks. This means that if you are checking a custom permission, it will only work if the feature part of the permission key (`org:<feature>:<permission>`) **is a feature included in the organization's active plan**. For example, say you want to check if an organization member has the custom permission `org:teams:manage`, where `teams` is the feature. Before performing the authorization check, you need to ensure that the user's organization is subscribed to a plan that has the `teams` feature. If the user's organization is not subscribed to a plan that has the `teams` feature, the authorization check will always return `false`, even if the user has the custom permission.
+> [!IMPORTANT]
+> Permission-based authorization checks link with feature-based authorization checks. This means that a permission check will only work if the feature part of the permission key (`org:<feature>:<permission>`) **is a feature included in the organization's active plan**. For example, say you want to check if an organization member has the custom permission `org:teams:manage`, where `teams` is the feature. Before performing the authorization check, you need to ensure that the user's organization is subscribed to a plan that has the `teams` feature. If not, the authorization check will always return `false`, even if the user has the custom permission.
 
 The `has()` method is available for any JavaScript framework, while `<Protect>` is only available for React-based frameworks.
 

docs/guides/organizations/roles-and-permissions.mdx

@@ -35,7 +35,7 @@ The **Creator** role must _at least_ have the following [system permissions](#sy
 
 To reassign the **Creator** role:
 
-1. In the Clerk Dashboard, navigate to [**Roles**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles).
+1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles).
 1. [Create a new role](#custom-roles) or use an existing role from the list.
 1. Ensure that **Manage members**, **Read members**, and **Delete organization** system permissions are selected for the role.
 1. Open the three dots icon for the role.
@@ -49,7 +49,7 @@ You cannot delete an organization role if it's used as the organization's **Defa
 
 To reassign the **Default** role:
 
-1. In the Clerk Dashboard, navigate to [**Roles**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles).
+1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles).
 1. [Create a new role](#custom-roles) or use an existing role from the list.
 1. Open the three dots icon for the role.
 1. From the dropdown, select the **Set as Default role** option.
@@ -65,10 +65,10 @@ Custom roles can be granted permissions and access. For example, you can create
 
 To create a new role:
 
-1. In the Clerk Dashboard, navigate to [**Roles**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles)
-1. Select **Create new role**.
-1. Give the role a name, a key to reference it by in the format `org:<role>`, and a description.
-1. Select **Create role**.
+1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles)
+1. Select **Add role**.
+1. Give the role a name, a key to reference it by, and a description. The final key will follow the format `org:<role>`.
+1. Select **Save**.
 
 ### Change a user's role
 
@@ -85,13 +85,18 @@ To change a user's role in the Clerk Dashboard:
 
 You cannot delete a role that is still assigned to members of an organization. Change the members to a different role before completing the following steps.
 
-1. In the Clerk Dashboard, navigate to [**Roles**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles).
+1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles).
 1. Select the three dots icon next to the role.
 1. Select **Delete role**.
 
 ## Permissions
 
-Permissions grant users privileged access to resources and operations, like creating and deleting. Clerk supports two types of permissions: System and Custom.
+Permissions grant users privileged access to resources and operations, like creating and deleting. Clerk supports two types of permissions: **System** and **Feature**.
+
+> [!IMPORTANT]
+> In the Clerk Dashboard, permissions appear in the format `<feature>:<permission>`. However, the `org:` prefix is automatically applied under the hood for all organization-scoped permissions. This means that when checking permissions in your code, always include the full key with the prefix (`org:<feature>:<permission>`).
+>
+> The examples and instructions in these docs follow the same `org:<feature>:<permission>` standard.
 
 ### System permissions
 
@@ -111,22 +116,24 @@ Clerk's system permissions consist of the following:
 You can assign these system permissions to any role.
 
 > [!WARNING]
-> System permissions aren't included in [session claims](/docs/guides/sessions/session-tokens#default-claims). To check permissions on the server-side, you must [create custom permissions](#custom-permissions).
+> System permissions aren't included in [session claims](/docs/guides/sessions/session-tokens#default-claims). To check permissions on the server-side, you must [create feature permissions](#feature-permissions).
 
-### Custom permissions
+### Feature permissions
 
 > [!WARNING]
-> Custom permissions require a [paid plan](/pricing){{ target: '_blank' }} and the Enhanced B2B SaaS Add-on for production use, but free to use in development mode so that you can try out what works for you. See the [pricing](/pricing){{ target: '_blank' }} page for more information.
-
-When creating a new permission, follow the format `org:<feature>:<permission>`. You can then assign the permission to an existing role.
+> Feature permissions require a [paid plan](/pricing){{ target: '_blank' }} and the Enhanced B2B SaaS Add-on for production use, but free to use in development mode so that you can try out what works for you. See the [pricing](/pricing){{ target: '_blank' }} page for more information.
 
-For example, you could create a new permission called **Create invoices** (`org:invoices:create`) which allows only users with this permission to edit invoices. Then, you could assign this permission to a role, or multiple roles, such as **Billing** (`org:billing`) or **Sales** (`org:sales`).
+Custom permissions let you define fine-tuned access control within your organization. Each permission is tied to a feature, and can be assigned to one or more roles. To create a custom permission, you must first create a role (e.g. **sales**) and a feature within that role (e.g. **invoices**). Once both exist, you can define specific permissions (e.g. **create**) related to that feature.
 
-To create a new permission:
+To create a new custom permission:
 
-1. In the Clerk Dashboard, navigate to [**Permissions**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles).
-1. Select **Create new permission**.
-1. Give the permission a name, a key to reference it by in the format `org:<feature>:<permission>`, and a description.
+1. In the Clerk Dashboard, navigate to [**Roles & Permissions**](https://dashboard.clerk.com/last-active?path=organizations-settings/roles).
+1. [Create a new role](#custom-roles) or use an existing role from the list.
+1. Under **Feature permissions**, select **Create feature permission**.
+1. Give the feature a name, a key to reference it by, and a description. The final key will follow the format `org:<feature>`.
+1. Select **Add feature**.
+1. Under the newly created feature, select **Create permission**.
+1. Give the permission a name, a key to reference it by, and a description. The final key will follow the format `org:<feature>:<permission>`.
    > [!NOTE]
    > Common permission values could be:
    >
@@ -138,6 +145,8 @@ To create a new permission:
    > For example, you could create a new permission called **Create invoices** (`org:invoices:create`) which allows only users with this permission to edit invoices. Then, you could assign this permission to a role, or multiple roles, such as **Billing** (`org:billing`) or **Sales** (`org:sales`).
 1. Select **Create permission**.
 
+You can also create a custom permission by navigating to the [**Features**](https://dashboard.clerk.com/last-active?path=features) tab in the Clerk Dashboard, and following steps 6-8 above.
+
 ## Verify a user's role or permission
 
 It's best practice to always verify whether or not a user is **authorized** to access sensitive information, important content, or exclusive features. **Authorization** is the process of determining the access rights and privileges of a user, ensuring they have the necessary permissions to perform specific actions. To perform authorization checks using a user's role or permission, see the [guide on authorizing users](/docs/guides/secure/authorization-checks).

docs/guides/secure/authorization-checks.mdx

@@ -41,7 +41,7 @@ This guide will show you how to implement authorization checks in order to prote
   - Note: Using `has()` **on the server-side** to check permissions works only with **custom permissions**, as [system permissions](/docs/guides/organizations/roles-and-permissions#system-permissions) aren't included in the session token claims. To check system permissions, verify the user's role instead.
 - Checking for a role or permission depends on the user having an [active organization](!active-organization). Without an active organization, the authorization checks will likely always evaluate to false by default.
 - If you would like to perform role-based authorization checks **without** using Clerk's organizations feature, see [the Role Based Access Control (RBAC) guide](/docs/guides/secure/basic-rbac).
-- Permission-based authorization checks link with feature-based authorization checks. This means that if you are checking a custom permission, it will only work if the feature part of the permission key (`org:<feature>:<permission>`) **is a feature included in the organization's active plan**. For example, say you want to check if an organization member has the custom permission `org:teams:manage`, where `teams` is the feature. Before performing the authorization check, you need to ensure that the user's organization is subscribed to a plan that has the `teams` feature. If the user's organization is not subscribed to a plan that has the `teams` feature, the authorization check will always return `false`, even if the user has the custom permission.
+- Permission-based authorization checks link with feature-based authorization checks. This means that a permission check will only work if the feature part of the permission key (`org:<feature>:<permission>`) **is a feature included in the organization's active plan**. For example, say you want to check if an organization member has the custom permission `org:teams:manage`, where `teams` is the feature. Before performing the authorization check, you need to ensure that the user's organization is subscribed to a plan that has the `teams` feature. If not, the authorization check will always return `false`, even if the user has the custom permission.
 
 <If sdk="nextjs">
   * Be cautious when doing authorization checks in layouts, as these don't re-render on navigation, meaning the user session won't be checked on every route change. [Read more in the Next.js docs](https://nextjs.org/docs/app/building-your-application/authentication#layouts-and-auth-checks).