Create an AWS Role Cloud Account¶
POST /api/v1/cloud_account/do/add
Overview¶
Create an AWS assume_role configuration for the current workspace and generate an independent External ID.
Before Calling and Usage Steps¶
Use the API Key of the target workspace. The four management entry points require cloudAccount.accountManage, and the Free Plan is explicitly denied. The account scope is the workspace to which the Key belongs. Reading temporary credentials requires the separate cloudAccount.temporaryCredentialsRead permission; management permissions do not automatically include it. Platform authorization is selected by the current brand and the cn/intl partition and does not fall back to other brands. All responses include Cache-Control: no-store and Pragma: no-cache.
First create the configuration and save uuid/externalId/platformAccountId, then have an authorized customer administrator or automation create the Role and permission policy in AWS, trust the platform account, and require the returned unique External ID. cn uses the aws-cn partition; intl uses aws. roleName must match the actual IAM Role path. If no Role has been created the first time, validationResult can be failed while creationResult remains created; continue using the same record to complete trust, then call modify with dryRun=true for validation, and finally use false to save. Do not use repeated creation to rotate the External ID. For complete steps, see Connect an AWS Cloud Account via OpenAPI; for site endpoints, see OpenAPI Site List.
The authorization context is generated automatically and does not accept dryRun/externalId/authorizationContext or customer AK/SK. During creation, first check for conflicts with an old accessKey/role under the same account, then deduplicate by Account ID (not by name); do not infer that creation did not occur because one fuzzy list query has no match. Validation includes one positive probe with the correct External ID and two negative probes with a missing/incorrect External ID, and both negative probes must be explicitly rejected. If validation fails, the record can still be saved normally with isAvailable=false; this does not mean the AWS resources have been created or the collection service permissions are complete.
After a timeout/5xx, first use list pagination and accurately check config.accountId and area, or restore the record using the existingCloudAccountUUIDs returned by the conflict. If saving of the configuration is not confirmed, the authorization fields are null; if an error occurs in a stage after submission, an error may coexist with creationResult.status=created, so it must be read back and verified.
Request Headers¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| DF-API-KEY | string | Y | OpenAPI authentication credential for the workspace. Example: <DF-API-KEY>How to obtain or enter: Obtain an OpenAPI Key with the required operation permission from API Key management in the target workspace. |
Body Request Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| config | object | Y | Required for creation, must be a complete configuration; for modification, required object; {} retains the original configuration but still validates, and dryRun=false may also resynchronize existing collection scripts. Do not add unpublished fields such as externalId/brand/workspace/long-term credentials.Null allowed: False Example: {}How to obtain or enter: Construct from the customer's AWS account/IAM role information and the fields below. |
| config.accountId | string | Y | Required for creation; business requires exactly 12 digits as a string, not a platform account ID/email/Role ARN. Modification does not accept changing the account; the same-named Query in list is a fuzzy filter, do not confuse them. Empty string allowed: True Null allowed: False Example: 123456789012How to obtain or enter: Obtain the 12-digit Account ID from the customer's AWS console account information, preserving leading zeros. |
| config.accountName | string | Y | Required non-empty string for creation; omitted on modification means keep; an empty string is rejected by business validation; maximum 256 weighted characters. Not an AWS login username or unique Account ID, and not used as a unique key for recovery. Null allowed: False Maximum length: 256 Example: example-accountHow to obtain or enter: A display name for the cloud account provided by the caller for identification. |
| config.area | custom_enum | Y | Required cn/intl on creation, corresponding to aws-cn/aws respectively; not a single AWS Region. Not accepted on modification; the original partition is fixed. Cannot be created when platform authorization for the current brand/partition is unavailable.Null allowed: False Allowed values: ['cn', 'intl'] Example: intlHow to obtain or enter: Select cn for the AWS China partition and intl for the global partition; must be consistent with the customer account and role ARN partition. |
| config.authType | custom_enum | Y | Required on creation and only assume_role; cannot be switched on modification, and do not use old role/accessKey.Null allowed: False Allowed values: ['assume_role'] Example: assume_roleHow to obtain or enter: Use third-party AWS IAM Role authorization. |
| config.extraTags | array | Optional, maximum 50 items; omitted on creation defaults to [], omitted on modification retains, [] clears; each item can only have key/value and both must be strings, and no additional fields can be added. This page manages tags and does not directly rewrite existing historical telemetry data.Null allowed: False Maximum length: 50 Example: [{"key": "env", "value": "prod"}]How to obtain or enter: Tag key-values selected by the customer to attach to cloud collection data; verify the actual business naming first. |
|
| config.extraTags[*] | object | A single object must have exactly key/value, with no null; duplicate keys are rejected, not last-one-wins.Example: {"key": "env", "value": "prod"}How to obtain or enter: One pair of business tag key-values. |
|
| config.extraTags[*].key | string | Conditionally required | Required non-empty, only letters/digits/_, maximum 256 UTF-8 bytes; __ prefix and the reserved keys account_id/account_name are prohibited; duplicates are not allowed in the same array.Null allowed: False Example: envHow to obtain or enter: Use a canonical business tag key. |
| config.extraTags[*].value | string | Conditionally required | Required non-empty string, maximum 1024 UTF-8 bytes; control characters and illegal surrogate characters are prohibited; numeric values must be explicitly converted to strings by the caller. Null allowed: False Example: prodHow to obtain or enter: The actual value of the business tag. |
| config.roleName | string | Y | Required for creation; omitted on modification means keep; non-empty ASCII path/name, cannot start with arn: or /, cannot end with /. The final name must be 1..64 characters, only letters/digits/_+=,.@-; the path follows the IAM rule of a maximum of 512 including separators, and the public total length upper limit is 575. Modification requires synchronization of the customer-side role and trust policy; you cannot change only the display name.Null allowed: False Maximum length: 575 Example: collection/ExampleCollectorHow to obtain or enter: Obtain the complete path and role name after role/ in the customer IAM role ARN. |
| provider | custom_enum | Y | Required on creation and only aws; not the Front multi-cloud account creation entry point; do not pass ak/sk or other cloud vendors.Null allowed: False Allowed values: ['aws'] Example: awsHow to obtain or enter: The current public management entry supports only AWS. |
Additional Parameter Details¶
Only AWS assume_role is supported; the caller must have the cloudAccount.accountManage permission for the current workspace, and the Free Plan is unavailable. Use DF-API-KEY; this permission does not automatically include temporary credential read permission.
Third-Party Automated Authorization¶
- Create the configuration and save the returned
uuid,externalId, andplatformAccountId. The first validation may fail, but the configuration can still be saved; HTTP success does not mean AWS authorization has passed. - The third party uses the customer-authorized AWS IAM/CloudFormation permissions to create the 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 customer AWS resources on the customer's behalf and does not accept customer AK/SK. - The Role path/name must match
config.roleName. After the customer deployment is complete, call the modify API{"config":{},"dryRun":true}to validate; after it passes, passdryRun=falseto revalidate and save. Back off with a bound for IAM propagation delay; do not repeatedly create or rotate the External ID. The role permission policy and trust policy are two separate configurations; trust success alone does not guarantee that all collection service permissions are complete. - Multi-account automation saves the UUID/External ID mapping per customer AWS account and does not share 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. One validation includes the original correct/missing/incorrect External ID probes.- Successful creation returns
uuid,externalId,platformAccountId, andisAvailable. A validation failure can also becreated; when creation is not confirmed successful, the authorization fields are null, and the HTTP error status is not changed to 200. - Does not accept
dryRun,externalId,authorizationContext, brand, or workspace override fields. Creation generates the External ID by the platform; no additional frontend operation is required. - If the same workspace and same AWS Account ID already have an old
accessKey/role, returnft.CloudAccountLegacyCredentialsConflict(409) andcontent.existingCloudAccountUUIDs; the user handles the old record and retries; only records that exist at creation time are checked, and permanent/concurrent mutual exclusion across entry points is not promised. - Duplicate creation follows the
ft.CloudAccountAKRepeatconflict and the existing record UUID, and does not automatically modify or replace. After a network timeout/5xx, first recover the record via list;accountIdis a fuzzy query, so you must paginate and accurately verifyconfig.accountId. Once found, use the original UUID/External ID. If not found, one query cannot prove that the previous request was not submitted; perform bounded queries, check conflict results, and then decide whether to retry. - Parameter/authentication/conflict failures before validation are
not_run; if locking or commit fails after validation completes, thispassed/failedis retained. 5xx returns a safe generic error and traceId, not the raw SQL/AWS response.
AWS references: Third-party cross-account authorization, CloudFormation Role.
Request Example¶
curl --request POST 'https://openapi.guance.com/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/ExampleCollector","accountName":"example-account","extraTags":[{"key":"env","value":"prod"}]}}'
Response¶
HTTP 200, application/json. The example below shows the main fields that can be read directly.
| Field | Type | Description |
|---|---|---|
| content.uuid | string or null | clac_ UUID when save is confirmed; otherwise null. |
| content.externalId | string or null | The independent External ID generated for this record, used to configure the AWS trust condition; null when save is unconfirmed. |
| content.platformAccountId | string or null | The platform AWS Account ID for the current brand/partition, not the customer Account ID; null when save is unconfirmed. |
| content.isAvailable | boolean or null | Availability of this validation, independent of whether it is saved. |
| content.creationResult | object | Creation/persistence operation result. |
| content.creationResult.status | string | Operation result status; see the creationResult or operationResult description. |
| content.creationResult.code | string | Operation error code, empty string on success; not equivalent to validationResult.code. |
| content.creationResult.message | string | Operation error description, empty string on success. |
| content.validationResult | object | Independent result of the same authorization probe; not a persistence conclusion. |
| content.validationResult.status | string | not_run means validation not completed; passed means passed; failed means executed but not passed. |
| content.validationResult.code | string | Empty string when passed; when failed, usually ft.CloudAccountAuthInvalid or ft.CloudAccountExternalIdTrustInvalid. |
| content.validationResult.message | string | Safe business description; does not echo the raw AWS response/long-term key. |
| content.existingCloudAccountUUIDs | array<string> | Present only in content of relevant conflict errors; UUIDs of recoverable records in this workspace. |
| content.existingCloudAccountUUIDs[] | string | A single cloud account UUID. |
| content.declaration | object | Outer public declaration for a successful response; self-returned errors do not add this declaration. |
| Response Header | Type | Description |
|---|---|---|
| Cache-Control | string | no-store; caching is prohibited for both success and errors on this blueprint route. |
| Pragma | string | no-cache. |
{
"code": 200,
"content": {
"uuid": "clac_example",
"externalId": "EXTERNAL-ID-EXAMPLE",
"platformAccountId": "111111111111",
"isAvailable": false,
"creationResult": {
"status": "created",
"code": "",
"message": ""
},
"validationResult": {
"status": "failed",
"code": "ft.CloudAccountAuthInvalid",
"message": "无效账号,请检查配置信息是否正确,并确保网络连接正常"
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
Customer-side trust policy example (the platform account/External ID must be replaced with the values returned for this record; for the cn partition, replace the ARN prefix with aws-cn; the required collection read permission policy is configured separately):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111111111111:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "EXTERNAL-ID-EXAMPLE"
}
}
}
]
}
Error Response¶
For authentication, rate limiting, and common request errors, see Common Error Definitions.
Public declaration/authentication layer failures may have only the standard content={}, and validationResult is not guaranteed to be present. After the four management entry points enter business adaptation, creation/modification failures may carry a safe operation result; their internal ordinary 5xx errors are uniformly returned by the service itself as 500 ft.CodeError, content retains the validation state from this request, and is not globally replaced with InternalServerError. Only ordinary uncaught exceptions at the temporary credential entry point go through the global 500 ft.InternalServerError. Do not look only at HTTP or success; you must judge based on the operation result, validation result, saved, and the read-back record.
| HTTP Status | errorCode | Trigger Condition | Message or Response Description | Handling |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | Request field missing, or field value violates the declared validation conditions | Parameter parsing failed | Verify the parameter location, field name, type, and value. |
| 400 | ft.RequestJsonFormatError | Invalid request JSON syntax | Request JSON format error | Fix the JSON according to content.reason, line, and column. |
| 400 | ft.JsonFormatError | Body top level is not a JSON object | Some JSON file format errors | Submit a JSON object that conforms to the example. |
| 403 | ft.Forbidden | The four management entry points are explicitly rejected by the version check in a Free Plan workspace | You do not have permission for this operation | Verify the workspace plan and management permissions; switch to a target workspace with the corresponding capabilities and authorization. |
| 404 | ft.InvalidCloudAccountType | The passed-in or target record is not an AWS assume_role | Invalid cloud account type | Take the record from the current workspace's dedicated cloud account list; old accessKey/role and other vendors cannot be used at this entry point. |
| 400 | ft.ParamsValidateError | The JSON Body is not an empty object {}, or a historically saved AWS assume_role configuration does not conform to the account/role/External ID specification |
Parameter validation failed: {} | Submit only {} in the request; if the historical configuration is invalid, check and repair it through the authorized cloud account management process, and do not pass dryRun/configuration update fields in this API. |
| 400 | ft.CloudAccountAssumeRoleCreationDisabled | Platform authorization for the current brand/partition is not enabled or the data is incomplete | The current environment does not support adding assume_role authorization; contact the administrator | Contact the administrator to verify support for this brand/partition; do not switch to another brand's platform ID. |
| 400 | ft.CloudAccountAuthorizationContextInvalid | The server-generated authorization context has expired or the identity/brand/configuration does not match | The authorization draft has expired or does not match the current operation; regenerate it | Check the current workspace/brand and concurrent changes; first query and recover the created record, then retry as instructed. |
| 409 | ft.CloudAccountLegacyCredentialsConflict | The same AWS Account ID already has an old accessKey/role non-deleted record | The current workspace already has an old credential record for this AWS account; manually delete the old record and retry | First use existingCloudAccountUUIDs to check old collection dependencies, and handle the old record according to business authorization; do not automatically overwrite it. |
| 400 | ft.CloudAccountAKRepeat | The same workspace already has an assume_role record with the same AWS Account ID | The current workspace already has the same {} {} |
Use the returned existingCloudAccountUUIDs and the original External ID; do not create the account again. |
| 429 | ft.OperationTooFrequently | Write lock contention/the lock has been lost, or the configuration was modified by another request during the wait | Your operation is too frequent, please retry later | Before bounded backoff, read back by UUID; do not overwrite the new submission based on an old snapshot; if the creation result is unknown, first recover by Account ID. |
| 500 | ft.CodeError | An internal exception occurred while reading the cloud account/historical JSON/collector data or displaying platform authorization | Internal processing error | Keep the traceId and Query; check the historical configuration/database and platform authorization; this read does not execute collection script deployment or configuration write. |