Create AWS Role Cloud Account¶
POST /api/v1/cloud_account/do/add
Body Request Parameters¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| provider | custom_enum | Y | Cloud provider Example: aws Allow empty: False Allowed values: ['aws'] |
| config | object | Y | Configuration Allow empty: False |
| config.authType | custom_enum | Y | Authentication type Example: assume_role Allow empty: False Allowed values: ['assume_role'] |
| config.area | custom_enum | Y | Region ID Example: cn Allow empty: False Allowed values: ['cn', 'intl'] |
| config.accountId | string | Y | The customer's 12-digit AWS account ID, submitted as a string Example: 123456789012 |
| config.roleName | string | Y | Authorized role name or path (assume_role supports paths; legacy role keeps the original restriction) Example: string Max length: 575 Allow empty: False |
| config.accountName | string | Y | Account name Example: string Max length: 256 Allow empty: False |
| config.extraTags | array | Cloud account tags; up to 50 items, omitted on edit to preserve, empty array to clear Max length: 50 Allow empty: False |
|
| config.extraTags[*] | object | ||
| config.extraTags[*].key | string | Y | Allow empty: False |
| config.extraTags[*].value | string | Y | Allow empty: False |
Additional Notes on Parameters¶
For end-to-end steps, see Connect an AWS cloud account via OpenAPI. The Endpoint in the example is taken from the OpenAPI site list.
Only AWS assume_role is supported; the caller must have the cloudAccount.accountManage permission for the current workspace. Use DF-API-KEY; this permission does not automatically include permission to read temporary credentials.
Third-Party Automation Authorization¶
- Create a configuration and save the returned
uuid,externalId, andplatformAccountId. The first validation may fail, but the configuration can still be saved; an HTTP success does not mean AWS authorization has passed. - The third party uses the customer's authorized AWS IAM/CloudFormation permissions to create a Role, configure the read permissions required for collection, and set the following trust policy.
cncorresponds toaws-cn, andintlcorresponds toaws; replace the platform account ID and External ID with the values returned for this record. OpenAPI does not manage the customer's AWS resources on their behalf, nor does it accept the customer's AK/SK. - The Role path/name must match
config.roleName. After the customer completes deployment, call the modify API with{"config":{},"dryRun":true}to validate; once it passes, passdryRun=falseto validate again and save. Apply bounded backoff for IAM propagation delays, and do not repeatedly create or rotate the External ID. A role's permission policy and trust policy are two independent configurations; trust alone succeeding does not guarantee that all collection service permissions are complete. - Multi-account automation saves the UUID/External ID mapping per customer AWS account without sharing External IDs. Cloud account management does not automatically install collectors.
Response and Recovery¶
creationResult.status:createdorfailed;validationResult.status:not_run,passed, orfailed, each carryingcode/message. A single validation includes the existing probes for correct, missing, and incorrect External IDs.- A successful creation returns
uuid,externalId,platformAccountId, andisAvailable. A failed validation can still becreated; when creation is not confirmed successful, the authorization fields are null, and an HTTP error status is not changed to 200. - It does not accept
dryRun,externalId,authorizationContext, brand, or workspace override fields. Creation generates the External ID on the platform, with no additional frontend operation required. - If a legacy
accessKey/rolealready exists for the same AWS Account ID in the same workspace, the API returnsft.CloudAccountLegacyCredentialsConflict(409) along withcontent.existingCloudAccountUUIDs; the user handles the legacy record and retries. Only records that exist at creation time are checked; permanent or concurrent mutual exclusion across entry points is not guaranteed. - Duplicate creation keeps the
ft.CloudAccountAKRepeatconflict and the existing record UUID; it does not automatically modify or replace anything. After a network timeout or 5xx, first recover the record using the list API;accountIdis a fuzzy query, so you must iterate through pages and precisely verifyconfig.accountId. Once the record is found, reuse its original UUID/External ID. If not found, do not treat a single query as proof that the previous request was definitely not submitted; perform bounded queries, verify the conflict results, and then decide whether to retry. - Failures before validation, such as parameter, authentication, or conflict errors, are
not_run; if a lock or commit failure occurs after validation completes, thepassed/failedresult from this attempt is still retained. 5xx responses return a safe generic error and a traceId, without returning raw SQL/AWS responses.
AWS references: Third-party cross-account access, CloudFormation Role.
Request Example¶
curl -X POST '<Endpoint>/api/v1/cloud_account/do/add' -H 'DF-API-KEY: <DF-API-KEY>' -H 'Content-Type: application/json' --data-raw '{"provider": "aws", "config": {"authType": "assume_role", "area": "intl", "accountId": "123456789012", "roleName": "collection/Guance", "accountName": "example", "extraTags": []}}'
Response¶
{
"code": 200,
"success": true,
"errorCode": "",
"message": "",
"content": {
"uuid": "clac_example",
"externalId": "generated-external-id",
"platformAccountId": "111111111111",
"isAvailable": false,
"creationResult": {
"status": "created",
"code": "",
"message": ""
},
"validationResult": {
"status": "failed",
"code": "ft.CloudAccountAuthInvalid",
"message": "Invalid cloud account authorization"
},
"declaration": {}
},
"traceId": "TRACE-example"
}