Update a control

Note: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.

PATCH https://api.ap1.datadoghq.com/api/v2/governance/control/{detection_type}https://api.ap2.datadoghq.com/api/v2/governance/control/{detection_type}https://api.datadoghq.eu/api/v2/governance/control/{detection_type}https://api.ddog-gov.com/api/v2/governance/control/{detection_type}https://api.us2.ddog-gov.com/api/v2/governance/control/{detection_type}https://api.uk1.datadoghq.com/api/v2/governance/control/{detection_type}https://api.datadoghq.com/api/v2/governance/control/{detection_type}https://api.us3.datadoghq.com/api/v2/governance/control/{detection_type}https://api.us5.datadoghq.com/api/v2/governance/control/{detection_type}

Overview

Update the detection, notification, and mitigation configuration of a governance control. Only the attributes present in the request are modified. Changing the mitigation type or its parameters may require additional permissions. This endpoint requires all of the following permissions:

  • governance_console_read
  • governance_console_write

  • Arguments

    Path Parameters

    Name

    Type

    Description

    detection_type [required]

    string

    The detection type that identifies the control, for example unused_api_keys.

    Request

    Body Data (required)

    Expand All

    Field

    Type

    Description

    data [required]

    object

    The data of a governance control update request.

    attributes

    object

    The attributes of a governance control that can be updated. Only the attributes present in the request are modified.

    detection_parameters

    object

    A free-form map of parameter names to their configured values.

    mitigation_parameters

    object

    A free-form map of parameter names to their configured values.

    mitigation_type

    string

    The mitigation type to configure for the control.

    type [required]

    enum

    JSON:API resource type for a governance control. Allowed enum values: governance_control

    {
      "data": {
        "attributes": {
          "detection_parameters": {},
          "mitigation_parameters": {},
          "mitigation_type": "revoke_api_key"
        },
        "type": "governance_control"
      }
    }

    Response

    OK

    A single governance control.

    Expand All

    Field

    Type

    Description

    data [required]

    object

    A governance control resource.

    attributes [required]

    object

    The attributes of a governance control.

    active_detections_count [required]

    int64

    The number of active detections for the control.

    category [required]

    string

    The value driver the control is grouped under, such as security or cost.

    created_at [required]

    date-time

    The time the control configuration was created.

    created_by [required]

    string

    The UUID of the user who created the control configuration.

    description [required]

    string

    A human-readable description of what the control detects.

    detection_parameters [required]

    object

    A free-form map of parameter names to their configured values.

    insights [required]

    [string]

    The insight slugs associated with the control.

    last_detection_at [required]

    date-time

    The time of the most recent detection for the control. null when there are no detections.

    mitigated_detections_count [required]

    int64

    The number of mitigated detections for the control.

    mitigation_parameters [required]

    object

    A free-form map of parameter names to their configured values.

    mitigation_type [required]

    string

    The configured mitigation type for the control. Empty when not configured.

    mitigations [required]

    [object]

    The mitigations available for a control.

    description [required]

    string

    A human-readable description of the mitigation.

    execution_modes [required]

    [string]

    The execution modes the mitigation supports, such as manual or automatic.

    id [required]

    string

    The unique identifier of the mitigation.

    permissions [required]

    [string]

    The permissions required to apply the mitigation.

    supported_parameters [required]

    [object]

    An array of parameter definitions.

    default_value [required]

    The default value of the parameter. The JSON type depends on the parameter's type.

    description [required]

    string

    A human-readable description of the parameter.

    display_name [required]

    string

    The human-readable name of the parameter.

    name [required]

    string

    The machine-readable name of the parameter.

    required [required]

    boolean

    Whether the parameter must be provided.

    supported_values [required]

    [object]

    The supported values for an enumerated parameter. null when the parameter is not an enumerated type.

    label [required]

    string

    The human-readable label for the value.

    value [required]

    string

    The machine-readable value.

    type [required]

    string

    The type of the parameter, such as integer, string, boolean, enum, or pattern_list.

    title [required]

    string

    A short, human-readable name for the mitigation.

    name [required]

    string

    Human-readable name of the control.

    priority [required]

    string

    The priority of the control, such as High.

    product [required]

    string

    The product the control belongs to.

    resource_type [required]

    string

    The type of resource the control evaluates.

    resource_type_display_name [required]

    string

    The human-readable name of the resource type.

    supported_detection_parameters [required]

    [object]

    An array of parameter definitions.

    default_value [required]

    The default value of the parameter. The JSON type depends on the parameter's type.

    description [required]

    string

    A human-readable description of the parameter.

    display_name [required]

    string

    The human-readable name of the parameter.

    name [required]

    string

    The machine-readable name of the parameter.

    required [required]

    boolean

    Whether the parameter must be provided.

    supported_values [required]

    [object]

    The supported values for an enumerated parameter. null when the parameter is not an enumerated type.

    label [required]

    string

    The human-readable label for the value.

    value [required]

    string

    The machine-readable value.

    type [required]

    string

    The type of the parameter, such as integer, string, boolean, enum, or pattern_list.

    type [required]

    string

    The control type, such as Proactive or Detection.

    id [required]

    string

    The detection type that uniquely identifies the control.

    type [required]

    enum

    JSON:API resource type for a governance control. Allowed enum values: governance_control

    {
      "data": {
        "attributes": {
          "active_detections_count": 12,
          "category": "security",
          "created_at": "2024-01-15T09:30:00Z",
          "created_by": "11111111-2222-3333-4444-555555555555",
          "description": "Identifies API keys that have not been used within your specified time threshold, helping reduce security risks from dormant credentials.",
          "detection_parameters": {},
          "insights": [
            []
          ],
          "last_detection_at": "2024-03-01T12:00:00Z",
          "mitigated_detections_count": 3,
          "mitigation_parameters": {},
          "mitigation_type": "revoke_api_key",
          "mitigations": [
            {
              "description": "Automatically identifies and revokes inactive API keys to improve security and reduce potential attack surface.",
              "execution_modes": [
                "manual",
                "automatic"
              ],
              "id": "revoke_api_key",
              "permissions": [
                "api_keys_write",
                "api_keys_delete"
              ],
              "supported_parameters": [
                {
                  "default_value": 30,
                  "description": "Number of days of inactivity before an API key is considered unused.",
                  "display_name": "Unused API Key Threshold",
                  "name": "api_key_threshold",
                  "required": false,
                  "supported_values": [
                    {
                      "label": "30 days",
                      "value": "thirty"
                    }
                  ],
                  "type": "integer"
                }
              ],
              "title": "Revoke Unused API Keys"
            }
          ],
          "name": "Unused API Keys",
          "priority": "High",
          "product": "api_keys",
          "resource_type": "api_key",
          "resource_type_display_name": "API Key",
          "supported_detection_parameters": [
            {
              "default_value": 30,
              "description": "Number of days of inactivity before an API key is considered unused.",
              "display_name": "Unused API Key Threshold",
              "name": "api_key_threshold",
              "required": false,
              "supported_values": [
                {
                  "label": "30 days",
                  "value": "thirty"
                }
              ],
              "type": "integer"
            }
          ],
          "type": "Proactive"
        },
        "id": "unused_api_keys",
        "type": "governance_control"
      }
    }

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [object]

    A list of errors.

    detail

    string

    A human-readable explanation specific to this occurrence of the error.

    meta

    object

    Non-standard meta-information about the error

    source

    object

    References to the source of the error.

    header

    string

    A string indicating the name of a single request header which caused the error.

    parameter

    string

    A string indicating which URI query parameter caused the error.

    pointer

    string

    A JSON pointer to the value in the request document that caused the error.

    status

    string

    Status code of the response.

    title

    string

    Short human-readable summary of the error.

    {
      "errors": [
        {
          "detail": "Missing required attribute in body",
          "meta": {},
          "source": {
            "header": "Authorization",
            "parameter": "limit",
            "pointer": "/data/attributes/title"
          },
          "status": "400",
          "title": "Bad Request"
        }
      ]
    }

    Unauthorized

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [object]

    A list of errors.

    detail

    string

    A human-readable explanation specific to this occurrence of the error.

    meta

    object

    Non-standard meta-information about the error

    source

    object

    References to the source of the error.

    header

    string

    A string indicating the name of a single request header which caused the error.

    parameter

    string

    A string indicating which URI query parameter caused the error.

    pointer

    string

    A JSON pointer to the value in the request document that caused the error.

    status

    string

    Status code of the response.

    title

    string

    Short human-readable summary of the error.

    {
      "errors": [
        {
          "detail": "Missing required attribute in body",
          "meta": {},
          "source": {
            "header": "Authorization",
            "parameter": "limit",
            "pointer": "/data/attributes/title"
          },
          "status": "400",
          "title": "Bad Request"
        }
      ]
    }

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [object]

    A list of errors.

    detail

    string

    A human-readable explanation specific to this occurrence of the error.

    meta

    object

    Non-standard meta-information about the error

    source

    object

    References to the source of the error.

    header

    string

    A string indicating the name of a single request header which caused the error.

    parameter

    string

    A string indicating which URI query parameter caused the error.

    pointer

    string

    A JSON pointer to the value in the request document that caused the error.

    status

    string

    Status code of the response.

    title

    string

    Short human-readable summary of the error.

    {
      "errors": [
        {
          "detail": "Missing required attribute in body",
          "meta": {},
          "source": {
            "header": "Authorization",
            "parameter": "limit",
            "pointer": "/data/attributes/title"
          },
          "status": "400",
          "title": "Bad Request"
        }
      ]
    }

    Not Found

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [object]

    A list of errors.

    detail

    string

    A human-readable explanation specific to this occurrence of the error.

    meta

    object

    Non-standard meta-information about the error

    source

    object

    References to the source of the error.

    header

    string

    A string indicating the name of a single request header which caused the error.

    parameter

    string

    A string indicating which URI query parameter caused the error.

    pointer

    string

    A JSON pointer to the value in the request document that caused the error.

    status

    string

    Status code of the response.

    title

    string

    Short human-readable summary of the error.

    {
      "errors": [
        {
          "detail": "Missing required attribute in body",
          "meta": {},
          "source": {
            "header": "Authorization",
            "parameter": "limit",
            "pointer": "/data/attributes/title"
          },
          "status": "400",
          "title": "Bad Request"
        }
      ]
    }

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Code Example

                      ## default
    # 
    
    # Path parameters
    export detection_type="unused_api_keys"
    # Curl command
    curl -X PATCH "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/governance/control/${detection_type}" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "detection_parameters": { "api_key_threshold": 60 }, "mitigation_type": "revoke_api_key" }, "type": "governance_control" } } EOF
    """
    Update a control returns "OK" response
    """
    
    from datadog_api_client import ApiClient, Configuration
    from datadog_api_client.v2.api.governance_console_api import GovernanceConsoleApi
    from datadog_api_client.v2.model.governance_control_resource_type import GovernanceControlResourceType
    from datadog_api_client.v2.model.governance_control_update_attributes import GovernanceControlUpdateAttributes
    from datadog_api_client.v2.model.governance_control_update_data import GovernanceControlUpdateData
    from datadog_api_client.v2.model.governance_control_update_request import GovernanceControlUpdateRequest
    
    body = GovernanceControlUpdateRequest(
        data=GovernanceControlUpdateData(
            attributes=GovernanceControlUpdateAttributes(
                mitigation_type="revoke_api_key",
            ),
            type=GovernanceControlResourceType.GOVERNANCE_CONTROL,
        ),
    )
    
    configuration = Configuration()
    configuration.unstable_operations["update_governance_control"] = True
    with ApiClient(configuration) as api_client:
        api_instance = GovernanceConsoleApi(api_client)
        response = api_instance.update_governance_control(detection_type="detection_type", body=body)
    
        print(response)
    

    Instructions

    First install the library and its dependencies and then save the example to example.py and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
    # Update a control returns "OK" response
    
    require "datadog_api_client"
    DatadogAPIClient.configure do |config|
      config.unstable_operations["v2.update_governance_control".to_sym] = true
    end
    api_instance = DatadogAPIClient::V2::GovernanceConsoleAPI.new
    
    body = DatadogAPIClient::V2::GovernanceControlUpdateRequest.new({
      data: DatadogAPIClient::V2::GovernanceControlUpdateData.new({
        attributes: DatadogAPIClient::V2::GovernanceControlUpdateAttributes.new({
          mitigation_type: "revoke_api_key",
        }),
        type: DatadogAPIClient::V2::GovernanceControlResourceType::GOVERNANCE_CONTROL,
      }),
    })
    p api_instance.update_governance_control("detection_type", body)
    

    Instructions

    First install the library and its dependencies and then save the example to example.rb and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
    // Update a control returns "OK" response
    
    package main
    
    import (
    	"context"
    	"encoding/json"
    	"fmt"
    	"os"
    
    	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
    	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
    )
    
    func main() {
    	body := datadogV2.GovernanceControlUpdateRequest{
    		Data: datadogV2.GovernanceControlUpdateData{
    			Attributes: &datadogV2.GovernanceControlUpdateAttributes{
    				MitigationType: datadog.PtrString("revoke_api_key"),
    			},
    			Type: datadogV2.GOVERNANCECONTROLRESOURCETYPE_GOVERNANCE_CONTROL,
    		},
    	}
    	ctx := datadog.NewDefaultContext(context.Background())
    	configuration := datadog.NewConfiguration()
    	configuration.SetUnstableOperationEnabled("v2.UpdateGovernanceControl", true)
    	apiClient := datadog.NewAPIClient(configuration)
    	api := datadogV2.NewGovernanceConsoleApi(apiClient)
    	resp, r, err := api.UpdateGovernanceControl(ctx, "detection_type", body)
    
    	if err != nil {
    		fmt.Fprintf(os.Stderr, "Error when calling `GovernanceConsoleApi.UpdateGovernanceControl`: %v\n", err)
    		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    	}
    
    	responseContent, _ := json.MarshalIndent(resp, "", "  ")
    	fmt.Fprintf(os.Stdout, "Response from `GovernanceConsoleApi.UpdateGovernanceControl`:\n%s\n", responseContent)
    }
    

    Instructions

    First install the library and its dependencies and then save the example to main.go and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
    // Update a control returns "OK" response
    
    import com.datadog.api.client.ApiClient;
    import com.datadog.api.client.ApiException;
    import com.datadog.api.client.v2.api.GovernanceConsoleApi;
    import com.datadog.api.client.v2.model.GovernanceControlResourceType;
    import com.datadog.api.client.v2.model.GovernanceControlResponse;
    import com.datadog.api.client.v2.model.GovernanceControlUpdateAttributes;
    import com.datadog.api.client.v2.model.GovernanceControlUpdateData;
    import com.datadog.api.client.v2.model.GovernanceControlUpdateRequest;
    
    public class Example {
      public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        defaultClient.setUnstableOperationEnabled("v2.updateGovernanceControl", true);
        GovernanceConsoleApi apiInstance = new GovernanceConsoleApi(defaultClient);
    
        GovernanceControlUpdateRequest body =
            new GovernanceControlUpdateRequest()
                .data(
                    new GovernanceControlUpdateData()
                        .attributes(
                            new GovernanceControlUpdateAttributes().mitigationType("revoke_api_key"))
                        .type(GovernanceControlResourceType.GOVERNANCE_CONTROL));
    
        try {
          GovernanceControlResponse result =
              apiInstance.updateGovernanceControl("unused_api_keys", body);
          System.out.println(result);
        } catch (ApiException e) {
          System.err.println("Exception when calling GovernanceConsoleApi#updateGovernanceControl");
          System.err.println("Status code: " + e.getCode());
          System.err.println("Reason: " + e.getResponseBody());
          System.err.println("Response headers: " + e.getResponseHeaders());
          e.printStackTrace();
        }
      }
    }
    

    Instructions

    First install the library and its dependencies and then save the example to Example.java and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
    // Update a control returns "OK" response
    use datadog_api_client::datadog;
    use datadog_api_client::datadogV2::api_governance_console::GovernanceConsoleAPI;
    use datadog_api_client::datadogV2::model::GovernanceControlResourceType;
    use datadog_api_client::datadogV2::model::GovernanceControlUpdateAttributes;
    use datadog_api_client::datadogV2::model::GovernanceControlUpdateData;
    use datadog_api_client::datadogV2::model::GovernanceControlUpdateRequest;
    
    #[tokio::main]
    async fn main() {
        let body = GovernanceControlUpdateRequest::new(
            GovernanceControlUpdateData::new(GovernanceControlResourceType::GOVERNANCE_CONTROL)
                .attributes(
                    GovernanceControlUpdateAttributes::new()
                        .mitigation_type("revoke_api_key".to_string()),
                ),
        );
        let mut configuration = datadog::Configuration::new();
        configuration.set_unstable_operation_enabled("v2.UpdateGovernanceControl", true);
        let api = GovernanceConsoleAPI::with_config(configuration);
        let resp = api
            .update_governance_control("detection_type".to_string(), body)
            .await;
        if let Ok(value) = resp {
            println!("{:#?}", value);
        } else {
            println!("{:#?}", resp.unwrap_err());
        }
    }
    

    Instructions

    First install the library and its dependencies and then save the example to src/main.rs and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
    /**
     * Update a control returns "OK" response
     */
    
    import { client, v2 } from "@datadog/datadog-api-client";
    
    const configuration = client.createConfiguration();
    configuration.unstableOperations["v2.updateGovernanceControl"] = true;
    const apiInstance = new v2.GovernanceConsoleApi(configuration);
    
    const params: v2.GovernanceConsoleApiUpdateGovernanceControlRequest = {
      body: {
        data: {
          attributes: {
            mitigationType: "revoke_api_key",
          },
          type: "governance_control",
        },
      },
      detectionType: "detection_type",
    };
    
    apiInstance
      .updateGovernanceControl(params)
      .then((data: v2.GovernanceControlResponse) => {
        console.log(
          "API called successfully. Returned data: " + JSON.stringify(data)
        );
      })
      .catch((error: any) => console.error(error));
    

    Instructions

    First install the library and its dependencies and then save the example to example.ts and run following commands:

        
    DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"