bump-sh · grossyoan · Apr 2, 2026 · Apr 1, 2026 · Apr 2, 2026
diff --git a/src/_data/sidebars/help.yml b/src/_data/sidebars/help.yml
@@ -101,6 +101,8 @@ resources:
                 link: /specification-support/extensions/
               - label: Badges
                 link: /specification-support/doc-badges/
+              - label: Roles requirements
+                link: /specification-support/roles-requirements/
               - label: Custom meta tags
                 link: /specification-support/meta-tags/
           - label: OpenAPI support

diff --git a/src/_help/specification-support/extensions.md b/src/_help/specification-support/extensions.md
@@ -41,4 +41,8 @@ This custom property lets you add custom meta tags in the `<head>` tag of your d
 
 ## Change tags display name (`x-displayName`)
 
-This custom property lets you change the display name of your OpenAPI tags. Find out more in our [dedicated section](/help/specification-support/openapi-support/x-display-name).
+This custom property lets you change the display name of your OpenAPI tags. Find out more in our [dedicated section](/help/specification-support/openapi-support/x-display-name).
+
+## Define role requirements (`x-rolesRequirements`)
+
+This custom property specifies which roles or permissions are required to access an endpoint. Find out more in our [dedicated section](/help/specification-support/roles-requirements).
diff --git a/src/_help/specification-support/roles-requirements.md b/src/_help/specification-support/roles-requirements.md
@@ -0,0 +1,44 @@
+---
+title: Role requirements
+---
+
+- TOC
+{:toc}
+
+Specify which roles or permissions are required to access an API endpoint with `x-rolesRequirements`. Combined with security schemes, this extension helps your API users understand both **what authentication method** they need and **what access levels or roles** their credentials must have.
+
+Add the `x-rolesRequirements` property to any OpenAPI/AsyncAPI operation or OpenAPI webhook. The property accepts either a string or an array of strings.
+
+### Example usage
+
+#### Using an array of strings
+
+```yaml
+paths:
+  /clusters:
+    post:
+      summary: Create a new cluster
+      x-rolesRequirements:
+        - Organization owner
+        - Product owner
+      # ... rest of operation
+```
+
+![Screenshot of an example API documentation on Bump.sh, with a multilines roles requirements area.](/docs/images/help/roles-requirements-multilines.png)
+
+#### Using a single string
+
+```yaml
+paths:
+  /clusters/{id}:
+    get:
+      summary: Get cluster details
+      x-rolesRequirements: "Cluster privileges: read"
+      # ... rest of operation
+```
+
+![Screenshot of an example API documentation on Bump.sh, with a single line roles requirements area.](/docs/images/help/roles-requirements-single-line.png)
+
+### Impact on the changelog
+
+Roles requirements updates are not visible in the changelog.
diff --git a/src/docs/images/help/roles-requirements-multilines.png b/src/docs/images/help/roles-requirements-multilines.png
diff --git a/src/docs/images/help/roles-requirements-single-line.png b/src/docs/images/help/roles-requirements-single-line.png