Connect an AWS Cloud Account Through OpenAPI¶
Using OpenAPI, you can create a role authorization configuration for an AWS account, configure the IAM trust relationship, and validate and save the authorization. In multi-account scenarios, you can repeat the same process for each AWS account.
Prerequisites¶
- Select the Endpoint of the site where the Workspace is located from the OpenAPI Site List.
- Prepare the API Key for the Workspace. Creating, querying, modifying, and deleting require the Cloud Account Management permission
cloudAccount.accountManage. - Prepare the customer's 12-digit AWS account ID, partition, and target IAM Role name. The examples use the international region (
area=intl, partitionaws) andcollection/CloudCollection. For the China region, usearea=cnand partitionaws-cn. - Confirm that the executing program has been authorized by the customer to create a Role in the target AWS account and add the permissions required for collection. The AWS CLI examples assume that the current AWS identity is configured as an authorized identity in that account.
The following examples use the environment variables API_BASE and DF_API_KEY, which represent the Endpoint (without a trailing slash) and the Workspace API Key loaded from secure storage, respectively.
1. Create a Cloud Account Configuration¶
Call Create AWS Role Cloud Account. Set config.accountId to the customer's own AWS account ID. The role path and name must match the Role actually created in the next step.
curl -sS -X POST "$API_BASE/api/v1/cloud_account/do/add" \
-H "DF-API-KEY: $DF_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"provider":"aws","config":{"authType":"assume_role","area":"intl","accountId":"123456789012","roleName":"collection/CloudCollection","accountName":"AWS collection"}}'
When content.creationResult.status is created, save the actual returned values of the following fields:
| Field | Purpose |
|---|---|
content.uuid |
Cloud account identifier for subsequent queries, validation, modification, and deletion |
content.externalId |
External ID generated by TrueWatch for the current configuration |
content.platformAccountId |
TrueWatch platform AWS account ID in the IAM trust policy |
Creating the configuration and validating the authorization return separate results. On the first call, the Role may not yet exist; in this case, you may receive both creationResult.status=created and validationResult.status=failed. Use the saved UUID and External ID to continue configuring AWS.
2. Create an IAM Role and Configure the Trust Policy¶
Create a Role in the customer's AWS account. Save the following JSON as trust-policy.json, and replace the partition, platform AWS account ID, and External ID. For the account ID in the trust policy, use the platformAccountId returned in the previous step.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:<partition>:iam::<platformAccountId>:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "<externalId>"
}
}
}
]
}
You can complete the configuration using the AWS console, AWS CLI, or a deployment template. When using the AWS CLI, collection/CloudCollection corresponds to the Role name CloudCollection and the IAM path /collection/.
aws iam create-role \
--role-name CloudCollection \
--path /collection/ \
--assume-role-policy-document file://trust-policy.json
aws iam put-role-policy \
--role-name CloudCollection \
--policy-name CloudCollectionRead \
--policy-document file://collection-policy.json
collection-policy.json is the collection permission policy approved by the customer. See the collection permission JSON in AWS Cloud Integration Role Authorization Configuration, and configure it according to the services actually collected. The trust policy controls who can assume the Role, while the permission policy controls the AWS resources that can be accessed after the Role is assumed.
For batch onboarding, maintain each AWS account's own UUID, partition, role path, and External ID. When reusing a deployment template, inject the corresponding values for each record. If a Role with the same name already exists, first verify the account, path, and purpose of that Role, and then update the trust and collection permissions according to the customer's IAM change process.
3. Validate and Save the Authorization¶
Set CLOUD_ACCOUNT_UUID to the UUID returned by the creation call, and call Modify or Validate AWS Role Cloud Account.
curl -sS -X POST "$API_BASE/api/v1/cloud_account/$CLOUD_ACCOUNT_UUID/do/modify" \
-H "DF-API-KEY: $DF_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"config":{},"dryRun":true}'
dryRun=true performs validation only, and content.saved=false is the expected result. Read content.validationResult.status. When the result is passed, submit {"config":{},"dryRun":false} to the same URL. The final save performs validation again. The authorization configuration is considered successfully validated and saved only when the response satisfies both content.saved=true and content.validationResult.status=passed.
If validation fails, verify the partition, role path, platform account, and External ID. The trust policy must reject AssumeRole requests that do not include an External ID or that include an incorrect External ID. If the IAM configuration was just updated, you can use the same UUID to perform a limited number of retries with backoff. After STS validation passes, configure Cloud Integration Collectors as needed, and verify the actual collection permissions.
4. Query, Recover, or Modify the Configuration¶
Use Query AWS Role Cloud Account to search precisely by uuid, or filter by accountId with pagination. List entries are in content.data, and pagination information is in pageInfo at the top level of the response.
curl -sS --get "$API_BASE/api/v1/cloud_account/do/list" \
-H "DF-API-KEY: $DF_API_KEY" \
--data-urlencode "uuid=$CLOUD_ACCOUNT_UUID"
If the creation response is lost, first query existing records. If you only know the AWS account ID, accountId is a fuzzy filter, so you must compare content.data[].config.accountId page by page for an exact match. If duplicate creation returns ft.CloudAccountAKRepeat, you can use content.existingCloudAccountUUIDs to locate the record. After recovery, continue using config.externalId and the platformAccountId of that record. If the platform authorization status is unavailable, wait for the platform configuration for the corresponding brand and partition to recover, and then query the platform account ID.
If creation encounters a legacy credential conflict ft.CloudAccountLegacyCredentialsConflict, first verify the returned UUID of the old record and evaluate its associated collectors, and then handle the original configuration. The modification API supports aliases, Role names, and tags. The account ID, partition, authentication type, and External ID are determined by the existing record. When updating tags, omitting extraTags keeps the original value, and passing [] clears them. Existing collectors may resynchronize during the final save.
5. Delete the Configuration or Read Temporary Credentials¶
When disabling the integration, verify the target UUID and associated collectors, and then send {} to Delete AWS Role Cloud Account. Deletion cleans up the platform configuration and associated collectors and tasks. The Role on the customer's AWS side is managed by the customer, and historical Observability data is retained. If you use a private Func, also confirm that the uninstall task has completed. If you recreate the integration later, you will receive a new UUID and External ID, and you must configure the IAM trust policy with the new values.
If your application needs temporary credentials, use an API Key with the cloudAccount.temporaryCredentialsRead permission to call Get AWS Temporary Credentials. The API validates the saved authorization in real time on each call and returns credentials with an expiration time. Use the credentials within their validity period and avoid writing them to logs.