Document include_scopes query param on GET /api/v2/permissions

.generator/schemas/v2/openapi.yaml

@@ -174662,6 +174662,19 @@ paths:
       description: |-
         Returns a list of all permissions, including name, description, and ID.
       operationId: ListPermissions
+      parameters:
+        - description: |-
+            Set to `true` to return all permissions, including both permissions
+            that can be assigned to user roles and permissions that can only be
+            used as scopes for OAuth clients and scoped credentials. When `false`
+            (default), only permissions that can be assigned to user roles are
+            returned.
+          example: false
+          in: query
+          name: include_scopes
+          required: false
+          schema:
+            type: boolean
       responses:
         "200":
           content:

examples/v2/roles/ListPermissions_1350046915.java

@@ -0,0 +1,26 @@
+// List permissions including scopes returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.RolesApi;
+import com.datadog.api.client.v2.api.RolesApi.ListPermissionsOptionalParameters;
+import com.datadog.api.client.v2.model.PermissionsResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    RolesApi apiInstance = new RolesApi(defaultClient);
+
+    try {
+      PermissionsResponse result =
+          apiInstance.listPermissions(new ListPermissionsOptionalParameters().includeScopes(true));
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling RolesApi#listPermissions");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

src/main/java/com/datadog/api/client/v2/api/RolesApi.java

@@ -928,6 +928,25 @@ public CompletableFuture<ApiResponse<RoleResponse>> getRoleWithHttpInfoAsync(Str
         new GenericType<RoleResponse>() {});
   }
 
+  /** Manage optional parameters to listPermissions. */
+  public static class ListPermissionsOptionalParameters {
+    private Boolean includeScopes;
+
+    /**
+     * Set includeScopes.
+     *
+     * @param includeScopes Set to <code>true</code> to return all permissions, including both
+     *     permissions that can be assigned to user roles and permissions that can only be used as
+     *     scopes for OAuth clients and scoped credentials. When <code>false</code> (default), only
+     *     permissions that can be assigned to user roles are returned. (optional)
+     * @return ListPermissionsOptionalParameters
+     */
+    public ListPermissionsOptionalParameters includeScopes(Boolean includeScopes) {
+      this.includeScopes = includeScopes;
+      return this;
+    }
+  }
+
   /**
    * List permissions.
    *
@@ -937,7 +956,7 @@ public CompletableFuture<ApiResponse<RoleResponse>> getRoleWithHttpInfoAsync(Str
    * @throws ApiException if fails to make API call
    */
   public PermissionsResponse listPermissions() throws ApiException {
-    return listPermissionsWithHttpInfo().getData();
+    return listPermissionsWithHttpInfo(new ListPermissionsOptionalParameters()).getData();
   }
 
   /**
@@ -948,7 +967,38 @@ public PermissionsResponse listPermissions() throws ApiException {
    * @return CompletableFuture&lt;PermissionsResponse&gt;
    */
   public CompletableFuture<PermissionsResponse> listPermissionsAsync() {
-    return listPermissionsWithHttpInfoAsync()
+    return listPermissionsWithHttpInfoAsync(new ListPermissionsOptionalParameters())
+        .thenApply(
+            response -> {
+              return response.getData();
+            });
+  }
+
+  /**
+   * List permissions.
+   *
+   * <p>See {@link #listPermissionsWithHttpInfo}.
+   *
+   * @param parameters Optional parameters for the request.
+   * @return PermissionsResponse
+   * @throws ApiException if fails to make API call
+   */
+  public PermissionsResponse listPermissions(ListPermissionsOptionalParameters parameters)
+      throws ApiException {
+    return listPermissionsWithHttpInfo(parameters).getData();
+  }
+
+  /**
+   * List permissions.
+   *
+   * <p>See {@link #listPermissionsWithHttpInfoAsync}.
+   *
+   * @param parameters Optional parameters for the request.
+   * @return CompletableFuture&lt;PermissionsResponse&gt;
+   */
+  public CompletableFuture<PermissionsResponse> listPermissionsAsync(
+      ListPermissionsOptionalParameters parameters) {
+    return listPermissionsWithHttpInfoAsync(parameters)
         .thenApply(
             response -> {
               return response.getData();
@@ -958,6 +1008,7 @@ public CompletableFuture<PermissionsResponse> listPermissionsAsync() {
   /**
    * Returns a list of all permissions, including name, description, and ID.
    *
+   * @param parameters Optional parameters for the request.
    * @return ApiResponse&lt;PermissionsResponse&gt;
    * @throws ApiException if fails to make API call
    * @http.response.details
@@ -970,18 +1021,23 @@ public CompletableFuture<PermissionsResponse> listPermissionsAsync() {
    *       <tr><td> 429 </td><td> Too many requests </td><td>  -  </td></tr>
    *     </table>
    */
-  public ApiResponse<PermissionsResponse> listPermissionsWithHttpInfo() throws ApiException {
+  public ApiResponse<PermissionsResponse> listPermissionsWithHttpInfo(
+      ListPermissionsOptionalParameters parameters) throws ApiException {
     Object localVarPostBody = null;
+    Boolean includeScopes = parameters.includeScopes;
     // create path and map variables
     String localVarPath = "/api/v2/permissions";
 
+    List<Pair> localVarQueryParams = new ArrayList<Pair>();
     Map<String, String> localVarHeaderParams = new HashMap<String, String>();
 
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "include_scopes", includeScopes));
+
     Invocation.Builder builder =
         apiClient.createBuilder(
             "v2.RolesApi.listPermissions",
             localVarPath,
-            new ArrayList<Pair>(),
+            localVarQueryParams,
             localVarHeaderParams,
             new HashMap<String, String>(),
             new String[] {"application/json"},
@@ -1002,22 +1058,28 @@ public ApiResponse<PermissionsResponse> listPermissionsWithHttpInfo() throws Api
    *
    * <p>See {@link #listPermissionsWithHttpInfo}.
    *
+   * @param parameters Optional parameters for the request.
    * @return CompletableFuture&lt;ApiResponse&lt;PermissionsResponse&gt;&gt;
    */
-  public CompletableFuture<ApiResponse<PermissionsResponse>> listPermissionsWithHttpInfoAsync() {
+  public CompletableFuture<ApiResponse<PermissionsResponse>> listPermissionsWithHttpInfoAsync(
+      ListPermissionsOptionalParameters parameters) {
     Object localVarPostBody = null;
+    Boolean includeScopes = parameters.includeScopes;
     // create path and map variables
     String localVarPath = "/api/v2/permissions";
 
+    List<Pair> localVarQueryParams = new ArrayList<Pair>();
     Map<String, String> localVarHeaderParams = new HashMap<String, String>();
 
+    localVarQueryParams.addAll(apiClient.parameterToPairs("", "include_scopes", includeScopes));
+
     Invocation.Builder builder;
     try {
       builder =
           apiClient.createBuilder(
               "v2.RolesApi.listPermissions",
               localVarPath,
-              new ArrayList<Pair>(),
+              localVarQueryParams,
               localVarHeaderParams,
               new HashMap<String, String>(),
               new String[] {"application/json"},

src/test/resources/cassettes/features/v2/List_permissions_including_scopes_returns_OK_response.freeze

@@ -0,0 +1 @@
+2026-08-05T16:12:34.510Z

src/test/resources/com/datadog/api/client/v2/api/roles.feature

@@ -203,6 +203,14 @@ Feature: Roles
     And the response "data[0].type" is equal to "{{ permission.type }}"
     And the response "data" has item with field "id" with value "{{ permission.id }}"
 
+  @team:DataDog/aaa-core-access @team:DataDog/access-policies-lifecycle
+  Scenario: List permissions including scopes returns "OK" response
+    Given new "ListPermissions" request
+    And request contains "include_scopes" parameter with value true
+    When the request is sent
+    Then the response status is 200 OK
+    And the response "data" has item with field "attributes.name" with value "admin"
+
   @generated @skip @team:DataDog/aaa-core-access @team:DataDog/access-policies-lifecycle
   Scenario: List permissions returns "Bad Request" response
     Given new "ListPermissions" request