These interfaces allow you to apply the Amazon Web Services library of pre-defined controls to your organizational units, programmatically. In Amazon Web Services Control Tower, the terms \"control\" and \"guardrail\" are synonyms.
To call these APIs, you'll need to know:
the controlIdentifier for the control--or guardrail--you are targeting.
the ARN associated with the target organizational unit (OU), which we call the targetIdentifier.
the ARN associated with a resource that you wish to tag or untag.
To get the controlIdentifier for your Amazon Web Services Control Tower control:
The controlIdentifier is an ARN that is specified for each control. You can view the controlIdentifier in the console on the Control details page, as well as in the documentation.
The controlIdentifier is unique in each Amazon Web Services Region for each control. You can find the controlIdentifier for each Region and control in the Tables of control metadata in the Amazon Web Services Control Tower User Guide.
A quick-reference list of control identifers for the Amazon Web Services Control Tower legacy Strongly recommended and Elective controls is given in Resource identifiers for APIs and controls in the Controls reference guide section of the Amazon Web Services Control Tower User Guide. Remember that Mandatory controls cannot be added or removed.
ARN format: arn:aws:controltower:{REGION}::control/{CONTROL_NAME}
Example:
arn:aws:controltower:us-west-2::control/AWS-GR_AUTOSCALING_LAUNCH_CONFIG_PUBLIC_IP_DISABLED
To get the targetIdentifier:
The targetIdentifier is the ARN for an OU.
In the Amazon Web Services Organizations console, you can find the ARN for the OU on the Organizational unit details page associated with that OU.
OU ARN format:
arn:${Partition}:organizations::${MasterAccountId}:ou/o-${OrganizationId}/ou-${OrganizationalUnitId}
Details and examples
To view the open source resource repository on GitHub, see aws-cloudformation/aws-cloudformation-resource-providers-controltower
Recording API Requests
Amazon Web Services Control Tower supports Amazon Web Services CloudTrail, a service that records Amazon Web Services API calls for your Amazon Web Services account and delivers log files to an Amazon S3 bucket. By using information collected by CloudTrail, you can determine which requests the Amazon Web Services Control Tower service received, who made the request and when, and so on. For more about Amazon Web Services Control Tower and its support for CloudTrail, see Logging Amazon Web Services Control Tower Actions with Amazon Web Services CloudTrail in the Amazon Web Services Control Tower User Guide. To learn more about CloudTrail, including how to turn it on and find your log files, see the Amazon Web Services CloudTrail User Guide.
", "operations": { "CreateLandingZone": "Creates a new landing zone. This API call starts an asynchronous operation that creates and configures a landing zone, based on the parameters specified in the manifest JSON file.
", "DeleteLandingZone": "Decommissions a landing zone. This API call starts an asynchronous operation that deletes Amazon Web Services Control Tower resources deployed in accounts managed by Amazon Web Services Control Tower.
", "DisableControl": "This API call turns off a control. It starts an asynchronous operation that deletes Amazon Web Services resources on the specified organizational unit and the accounts it contains. The resources will vary according to the control that you specify. For usage examples, see the Amazon Web Services Control Tower User Guide .
", "EnableControl": "This API call activates a control. It starts an asynchronous operation that creates Amazon Web Services resources on the specified organizational unit and the accounts it contains. The resources created will vary according to the control that you specify. For usage examples, see the Amazon Web Services Control Tower User Guide .
", "GetControlOperation": "Returns the status of a particular EnableControl or DisableControl operation. Displays a message in case of error. Details for an operation are available for 90 days. For usage examples, see the Amazon Web Services Control Tower User Guide .
Retrieves details about an enabled control. For usage examples, see the Amazon Web Services Control Tower User Guide .
", "GetLandingZone": "Returns details about the landing zone. Displays a message in case of error.
", "GetLandingZoneOperation": "Returns the status of the specified landing zone operation. Details for an operation are available for 60 days.
", "ListEnabledControls": "Lists the controls enabled by Amazon Web Services Control Tower on the specified organizational unit and the accounts it contains. For usage examples, see the Amazon Web Services Control Tower User Guide .
", "ListLandingZones": "Returns the landing zone ARN for the landing zone deployed in your managed account. This API also creates an ARN for existing accounts that do not yet have a landing zone ARN.
Returns one landing zone ARN.
", "ListTagsForResource": "Returns a list of tags associated with the resource. For usage examples, see the Amazon Web Services Control Tower User Guide .
", "ResetLandingZone": "This API call resets a landing zone. It starts an asynchronous operation that resets the landing zone to the parameters specified in its original configuration.
", "TagResource": "Applies tags to a resource. For usage examples, see the Amazon Web Services Control Tower User Guide .
", "UntagResource": "Removes tags from a resource. For usage examples, see the Amazon Web Services Control Tower User Guide .
", "UpdateEnabledControl": "Updates the configuration of an already enabled control.
If the enabled control shows an EnablementStatus of SUCCEEDED, supply parameters that are different from the currently configured parameters. Otherwise, Amazon Web Services Control Tower will not accept the request.
If the enabled control shows an EnablementStatus of FAILED, Amazon Web Services Control Tower will update the control to match any valid parameters that you supply.
If the DriftSummary status for the control shows as DRIFTED, you cannot call this API. Instead, you can update the control by calling DisableControl and again calling EnableControl, or you can run an extending governance operation. For usage examples, see the Amazon Web Services Control Tower User Guide
This API call updates the landing zone. It starts an asynchronous operation that updates the landing zone based on the new landing zone version, or on the changed parameters specified in the updated manifest file.
" }, "shapes": { "AccessDeniedException": { "base": "You do not have sufficient access to perform this action.
", "refs": { } }, "Arn": { "base": null, "refs": { "CreateLandingZoneOutput$arn": "The ARN of the landing zone resource.
", "EnableControlOutput$arn": "The ARN of the EnabledControl resource.
The ARN of the enabled control.
", "EnabledControlSummary$arn": "The ARN of the enabled control.
", "GetEnabledControlInput$enabledControlIdentifier": "The controlIdentifier of the enabled control.
The ARN of the landing zone.
", "LandingZoneSummary$arn": "The ARN of the landing zone.
", "ListTagsForResourceInput$resourceArn": "The ARN of the resource.
", "TagResourceInput$resourceArn": "The ARN of the resource to be tagged.
", "UntagResourceInput$resourceArn": "The ARN of the resource.
", "UpdateEnabledControlInput$enabledControlIdentifier": "The ARN of the enabled control that will be updated.
" } }, "ConflictException": { "base": "Updating or deleting the resource can cause an inconsistent state.
", "refs": { } }, "ControlIdentifier": { "base": null, "refs": { "DisableControlInput$controlIdentifier": "The ARN of the control. Only Strongly recommended and Elective controls are permitted, with the exception of the landing zone Region deny control. For information on how to find the controlIdentifier, see the overview page.
The ARN of the control. Only Strongly recommended and Elective controls are permitted, with the exception of the landing zone Region deny control. For information on how to find the controlIdentifier, see the overview page.
The control identifier of the enabled control. For information on how to find the controlIdentifier, see the overview page.
The controlIdentifier of the enabled control.
An operation performed by the control.
", "refs": { "GetControlOperationOutput$controlOperation": "An operation performed by the control.
" } }, "ControlOperationStatus": { "base": null, "refs": { "ControlOperation$status": "One of IN_PROGRESS, SUCEEDED, or FAILED.
One of ENABLE_CONTROL or DISABLE_CONTROL.
The value of a key/value pair. It can be of type array string, number, object, or boolean.
The value of a key/value pair.
" } }, "DriftStatus": { "base": null, "refs": { "DriftStatusSummary$driftStatus": "The drift status of the enabled control.
Valid values:
DRIFTED: The enabledControl deployed in this configuration doesn’t match the configuration that Amazon Web Services Control Tower expected.
IN_SYNC: The enabledControl deployed in this configuration matches the configuration that Amazon Web Services Control Tower expected.
NOT_CHECKING: Amazon Web Services Control Tower does not check drift for this enabled control. Drift is not supported for the control type.
UNKNOWN: Amazon Web Services Control Tower is not able to check the drift status for the enabled control.
The drift summary of the enabled control.
Amazon Web Services Control Tower expects the enabled control configuration to include all supported and governed Regions. If the enabled control differs from the expected configuration, it is defined to be in a state of drift. You can repair this drift by resetting the enabled control.
", "refs": { "EnabledControlDetails$driftStatusSummary": "The drift status of the enabled control.
", "EnabledControlSummary$driftStatusSummary": "The drift status of the enabled control.
" } }, "EnableControlInput": { "base": null, "refs": { } }, "EnableControlOutput": { "base": null, "refs": { } }, "EnabledControlDetails": { "base": "Information about the enabled control.
", "refs": { "GetEnabledControlOutput$enabledControlDetails": "Information about the enabled control.
" } }, "EnabledControlParameter": { "base": " A set of parameters that configure the behavior of the enabled control. A key/value pair, where Key is of type String and Value is of type Document.
Array of EnabledControlParameter objects.
Returns a summary of information about the parameters of an enabled control.
", "refs": { "EnabledControlParameterSummaries$member": null } }, "EnabledControlParameters": { "base": null, "refs": { "EnableControlInput$parameters": "An array of EnabledControlParameter objects
A key/value pair, where Key is of type String and Value is of type Document.
Returns a summary of information about an enabled control.
", "refs": { "EnabledControls$member": null } }, "EnabledControls": { "base": null, "refs": { "ListEnabledControlsOutput$enabledControls": "Lists the controls enabled by Amazon Web Services Control Tower on the specified organizational unit and the accounts it contains.
" } }, "EnablementStatus": { "base": null, "refs": { "EnablementStatusSummary$status": "The deployment status of the enabled control.
Valid values:
SUCCEEDED: The enabledControl configuration was deployed successfully.
UNDER_CHANGE: The enabledControl configuration is changing.
FAILED: The enabledControl configuration failed to deploy.
The deployment summary of the enabled control.
", "refs": { "EnabledControlDetails$statusSummary": "The deployment summary of the enabled control.
", "EnabledControlSummary$statusSummary": "A short description of the status of the enabled control.
" } }, "GetControlOperationInput": { "base": null, "refs": { } }, "GetControlOperationOutput": { "base": null, "refs": { } }, "GetEnabledControlInput": { "base": null, "refs": { } }, "GetEnabledControlOutput": { "base": null, "refs": { } }, "GetLandingZoneInput": { "base": null, "refs": { } }, "GetLandingZoneOperationInput": { "base": null, "refs": { } }, "GetLandingZoneOperationOutput": { "base": null, "refs": { } }, "GetLandingZoneOutput": { "base": null, "refs": { } }, "Integer": { "base": null, "refs": { "ThrottlingException$retryAfterSeconds": "The number of seconds to wait before retrying.
" } }, "InternalServerException": { "base": "An unexpected error occurred during processing of a request.
", "refs": { } }, "LandingZoneDetail": { "base": "Information about the landing zone.
", "refs": { "GetLandingZoneOutput$landingZone": "Information about the landing zone.
" } }, "LandingZoneDriftStatus": { "base": null, "refs": { "LandingZoneDriftStatusSummary$status": "The drift status of the landing zone.
Valid values:
DRIFTED: The landing zone deployed in this configuration does not match the configuration that Amazon Web Services Control Tower expected.
IN_SYNC: The landing zone deployed in this configuration matches the configuration that Amazon Web Services Control Tower expected.
The drift status summary of the landing zone.
If the landing zone differs from the expected configuration, it is defined to be in a state of drift. You can repair this drift by resetting the landing zone.
", "refs": { "LandingZoneDetail$driftStatus": "The drift status of the landing zone.
" } }, "LandingZoneOperationDetail": { "base": "Information about a landing zone operation.
", "refs": { "GetLandingZoneOperationOutput$operationDetails": "Details about a landing zone operation.
" } }, "LandingZoneOperationStatus": { "base": null, "refs": { "LandingZoneOperationDetail$status": "Valid values:
SUCCEEDED: The landing zone operation succeeded.
IN_PROGRESS: The landing zone operation is in progress.
FAILED: The landing zone operation failed.
The landing zone operation type.
Valid values:
DELETE: The DeleteLandingZone operation.
CREATE: The CreateLandingZone operation.
UPDATE: The UpdateLandingZone operation.
RESET: The ResetLandingZone operation.
The landing zone deployment status.
" } }, "LandingZoneSummary": { "base": "Returns a summary of information about a landing zone.
", "refs": { "ListLandingZonesOutputLandingZonesList$member": null } }, "LandingZoneVersion": { "base": null, "refs": { "CreateLandingZoneInput$version": "The landing zone version, for example, 3.0.
", "LandingZoneDetail$latestAvailableVersion": "The latest available version of the landing zone.
", "LandingZoneDetail$version": "The landing zone's current deployed version.
", "UpdateLandingZoneInput$version": "The landing zone version, for example, 3.2.
" } }, "ListEnabledControlsInput": { "base": null, "refs": { } }, "ListEnabledControlsOutput": { "base": null, "refs": { } }, "ListLandingZonesInput": { "base": null, "refs": { } }, "ListLandingZonesMaxResults": { "base": null, "refs": { "ListLandingZonesInput$maxResults": "The maximum number of returned landing zone ARNs, which is one.
" } }, "ListLandingZonesOutput": { "base": null, "refs": { } }, "ListLandingZonesOutputLandingZonesList": { "base": null, "refs": { "ListLandingZonesOutput$landingZones": "The ARN of the landing zone.
" } }, "ListTagsForResourceInput": { "base": null, "refs": { } }, "ListTagsForResourceOutput": { "base": null, "refs": { } }, "Manifest": { "base": null, "refs": { "CreateLandingZoneInput$manifest": "The manifest JSON file is a text file that describes your Amazon Web Services resources. For examples, review Launch your landing zone.
", "LandingZoneDetail$manifest": "The landing zone manifest JSON text file that specifies the landing zone configurations.
", "UpdateLandingZoneInput$manifest": "The manifest JSON file is a text file that describes your Amazon Web Services resources. For examples, review Launch your landing zone.
" } }, "MaxResults": { "base": null, "refs": { "ListEnabledControlsInput$maxResults": "How many results to return per API call.
" } }, "OperationIdentifier": { "base": null, "refs": { "CreateLandingZoneOutput$operationIdentifier": "A unique identifier assigned to a CreateLandingZone operation. You can use this identifier as an input of GetLandingZoneOperation to check the operation's status.
>A unique identifier assigned to a DeleteLandingZone operation. You can use this identifier as an input parameter of GetLandingZoneOperation to check the operation's status.
The ID of the asynchronous operation, which is used to track status. The operation is available for 90 days.
", "EnableControlOutput$operationIdentifier": "The ID of the asynchronous operation, which is used to track status. The operation is available for 90 days.
", "EnablementStatusSummary$lastOperationIdentifier": "The last operation identifier for the enabled control.
", "GetControlOperationInput$operationIdentifier": "The ID of the asynchronous operation, which is used to track status. The operation is available for 90 days.
", "GetLandingZoneOperationInput$operationIdentifier": "A unique identifier assigned to a landing zone operation.
", "ResetLandingZoneOutput$operationIdentifier": "A unique identifier assigned to a ResetLandingZone operation. You can use this identifier as an input parameter of GetLandingZoneOperation to check the operation's status.
The operation identifier for this UpdateEnabledControl operation.
A unique identifier assigned to a UpdateLandingZone operation. You can use this identifier as an input of GetLandingZoneOperation to check the operation's status.
An Amazon Web Services Region in which Amazon Web Services Control Tower expects to find the control deployed.
The expected Regions are based on the Regions that are governed by the landing zone. In certain cases, a control is not actually enabled in the Region as expected, such as during drift, or mixed governance.
", "refs": { "TargetRegions$member": null } }, "RegionName": { "base": null, "refs": { "Region$name": "The Amazon Web Services Region name.
" } }, "ResetLandingZoneInput": { "base": null, "refs": { } }, "ResetLandingZoneOutput": { "base": null, "refs": { } }, "ResourceNotFoundException": { "base": "The request references a resource that does not exist.
", "refs": { } }, "ServiceQuotaExceededException": { "base": "The request would cause a service quota to be exceeded. The limit is 10 concurrent operations.
", "refs": { } }, "String": { "base": null, "refs": { "AccessDeniedException$message": null, "ConflictException$message": null, "ControlOperation$statusMessage": "If the operation result is FAILED, this string contains a message explaining why the operation failed.
The unique identifier of the landing zone.
", "EnabledControlParameter$key": "The key of a key/value pair. It is of type string.
The key of a key/value pair.
", "GetLandingZoneInput$landingZoneIdentifier": "The unique identifier of the landing zone.
", "InternalServerException$message": null, "LandingZoneOperationDetail$statusMessage": "If the operation result is FAILED, this string contains a message explaining why the operation failed.
", "ListEnabledControlsInput$nextToken": "The token to continue the list from a previous API call with the same parameters.
", "ListEnabledControlsOutput$nextToken": "Retrieves the next page of results. If the string is empty, the response is the end of the results.
", "ListLandingZonesInput$nextToken": "The token to continue the list from a previous API call with the same parameters.
", "ListLandingZonesOutput$nextToken": "Retrieves the next page of results. If the string is empty, the response is the end of the results.
", "ResetLandingZoneInput$landingZoneIdentifier": "The unique identifier of the landing zone.
", "ResourceNotFoundException$message": null, "ServiceQuotaExceededException$message": null, "ThrottlingException$message": null, "ThrottlingException$quotaCode": "The ID of the service quota that was exceeded.
", "ThrottlingException$serviceCode": "The ID of the service that is associated with the error.
", "UpdateLandingZoneInput$landingZoneIdentifier": "The unique identifier of the landing zone.
", "ValidationException$message": null } }, "SyntheticTimestamp_date_time": { "base": null, "refs": { "ControlOperation$endTime": "The time that the operation finished.
", "ControlOperation$startTime": "The time that the operation began.
" } }, "TagKey": { "base": null, "refs": { "TagKeys$member": null, "TagMap$key": null } }, "TagKeys": { "base": null, "refs": { "UntagResourceInput$tagKeys": "Tag keys to be removed from the resource.
" } }, "TagMap": { "base": null, "refs": { "CreateLandingZoneInput$tags": "Tags to be applied to the landing zone.
", "EnableControlInput$tags": "Tags to be applied to the EnabledControl resource.
A list of tags, as key:value strings.
Tags to be applied to the resource.
" } }, "TagResourceInput": { "base": null, "refs": { } }, "TagResourceOutput": { "base": null, "refs": { } }, "TagValue": { "base": null, "refs": { "TagMap$value": null } }, "TargetIdentifier": { "base": null, "refs": { "DisableControlInput$targetIdentifier": "The ARN of the organizational unit. For information on how to find the targetIdentifier, see the overview page.
The ARN of the organizational unit. For information on how to find the targetIdentifier, see the overview page.
The ARN of the organizational unit. For information on how to find the targetIdentifier, see the overview page.
The ARN of the organizational unit.
", "ListEnabledControlsInput$targetIdentifier": "The ARN of the organizational unit. For information on how to find the targetIdentifier, see the overview page.
Target Amazon Web Services Regions for the enabled control.
" } }, "ThrottlingException": { "base": "The request was denied due to request throttling.
", "refs": { } }, "Timestamp": { "base": null, "refs": { "LandingZoneOperationDetail$endTime": "The landing zone operation end time.
", "LandingZoneOperationDetail$startTime": "The landing zone operation start time.
" } }, "UntagResourceInput": { "base": null, "refs": { } }, "UntagResourceOutput": { "base": null, "refs": { } }, "UpdateEnabledControlInput": { "base": null, "refs": { } }, "UpdateEnabledControlOutput": { "base": null, "refs": { } }, "UpdateLandingZoneInput": { "base": null, "refs": { } }, "UpdateLandingZoneOutput": { "base": null, "refs": { } }, "ValidationException": { "base": "The input does not satisfy the constraints specified by an Amazon Web Services service.
", "refs": { } } } }