Document DDSQL query permissions and OAuth scope

.generator/schemas/v2/openapi.yaml

@@ -151871,6 +151871,13 @@ paths:
         Submit a DDSQL statement and return either a `running` state with an opaque `query_id`
         for the client to poll, or a `completed` state with the column-major result set inlined
         when the query finishes quickly enough to be served synchronously.
+
+        For a scoped application key, include `timeseries_query` in its scopes.
+        A query that does not read a data source, such as `SELECT 1`, requires no additional
+        data-source permissions. Queries that read data sources also require the user or
+        service account that owns the application key to have the corresponding data access
+        permissions through their roles. The `timeseries_query` permission does not grant
+        access to the underlying data sources.
       operationId: ExecuteDdsqlTabularQuery
       requestBody:
         content:
@@ -151973,16 +151980,30 @@ paths:
               schema:
                 $ref: "#/components/schemas/JSONAPIErrorResponse"
           description: Internal Server Error
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - timeseries_query
       summary: Execute a tabular DDSQL query
       tags:
         - DDSQL
+      "x-permission":
+        operator: OR
+        permissions:
+          - timeseries_query
   /api/v2/ddsql/query/tabular/fetch:
     post:
       description: |-
         Poll a previously submitted DDSQL query for results. Pass the opaque `query_id` returned
         by a prior `ExecuteDdsqlTabularQuery` (or by a prior `FetchDdsqlTabularQuery` that
         returned `state: running`) and the server returns either a `running` state to poll again
         or a `completed` state with the column-major result set inlined.
+
+        For a scoped application key, include `timeseries_query` in its scopes.
+        Fetch results as the same user and organization that submitted the query.
+        The user or service account that owns the application key must have the data access
+        permissions required by the queried data sources through their roles.
       operationId: FetchDdsqlTabularQuery
       requestBody:
         content:
@@ -152081,9 +152102,18 @@ paths:
               schema:
                 $ref: "#/components/schemas/JSONAPIErrorResponse"
           description: Internal Server Error
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - timeseries_query
       summary: Fetch the result of a DDSQL query
       tags:
         - DDSQL
+      "x-permission":
+        operator: OR
+        permissions:
+          - timeseries_query
   /api/v2/deletion/data/{product}:
     post:
       description: Creates a data deletion request by providing a query and a timeframe targeting the proper data.

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

@@ -81,6 +81,13 @@ public CompletableFuture<DdsqlTabularQueryResponse> executeDdsqlTabularQueryAsyn
    * query_id</code> for the client to poll, or a <code>completed</code> state with the column-major
    * result set inlined when the query finishes quickly enough to be served synchronously.
    *
+   * <p>For a scoped application key, include <code>timeseries_query</code> in its scopes. A query
+   * that does not read a data source, such as <code>SELECT 1</code>, requires no additional
+   * data-source permissions. Queries that read data sources also require the user or service
+   * account that owns the application key to have the corresponding data access permissions through
+   * their roles. The <code>timeseries_query</code> permission does not grant access to the
+   * underlying data sources.
+   *
    * @param body (required)
    * @return ApiResponse&lt;DdsqlTabularQueryResponse&gt;
    * @throws ApiException if fails to make API call
@@ -219,6 +226,11 @@ public CompletableFuture<DdsqlTabularQueryResponse> fetchDdsqlTabularQueryAsync(
    * either a <code>running</code> state to poll again or a <code>completed</code> state with the
    * column-major result set inlined.
    *
+   * <p>For a scoped application key, include <code>timeseries_query</code> in its scopes. Fetch
+   * results as the same user and organization that submitted the query. The user or service account
+   * that owns the application key must have the data access permissions required by the queried
+   * data sources through their roles.
+   *
    * @param body (required)
    * @return ApiResponse&lt;DdsqlTabularQueryResponse&gt;
    * @throws ApiException if fails to make API call