Modify or Validate AWS Role Cloud Account¶
POST /api/v1/cloud_account/{cloud_account_uuid}/do/modify
Overview¶
Validate or modify the existing AWS assume_role configuration in the current workspace.
Before Calling and Usage Steps¶
Use the target workspace's API Key. 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. Temporary credential reads require the separate cloudAccount.temporaryCredentialsRead permission, which is not automatically included in management permissions. Platform authorization is selected based on the current workspace's brand and cn/intl partition, with no fallback to other brands; all responses include Cache-Control: no-store and Pragma: no-cache.
dryRun must be explicit, and config is required; {} validates the original configuration. Only accountName/roleName/extraTags can be changed; omitted fields are retained; tags set to [] are cleared. Changing accountId/area/authType/External ID is not supported, and this is not an entry point for migrating old roles.
When dryRun=true, a real STS validation is performed synchronously; the account is not saved and collection scripts are not deployed, and saved=false. Even if authorization fails, the response can still be HTTP 200 with operationResult=completed and validationResult=failed. When dryRun=false, validation is also performed first, after which the account can be saved with isAvailable=false; saved=true only indicates that persistence processing is complete (including resynchronization when the configuration is unchanged), not that validation passed or collection succeeded.
If collectors already exist, a formal save rebuilds/deploys scripts; resynchronization may occur even if the configuration is unchanged. External deployment and the database are not cross-service atomic transactions; on failure, recovery/uninstallation is attempted based on the current persisted configuration. If recovery fails, an administrator must investigate; do not claim that everything has been rolled back. Concurrent configuration changes reject overwrites from old snapshots. For validation only, saved=false; for a formal failure where it is not yet certain, it can be null; on success, it is true.
First create the configuration and save uuid/externalId/platformAccountId; then an authorized customer administrator or automation creates the Role and permission policy in AWS, trusts the platform account, and requires the unique External ID returned. cn uses the aws-cn partition, and intl uses aws; roleName must match the actual IAM Role path. If the Role has not been created on first attempt, validationResult can be failed while creationResult remains created. Continue using the same record to complete trust, then call modify with dryRun=true to validate, and finally save with false. Do not rotate the External ID by creating the account repeatedly. For complete steps, see Connect an AWS Cloud Account via OpenAPI. For site Endpoint, see OpenAPI Site List.
Route Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| cloud_account_uuid | string | Y | Path is required; must be a non-deleted AWS assume_role record; do not use the customer Account ID, role ARN, or another workspace UUID. Allows empty string: False Example: clac_exampleHow to obtain or specify: Obtain the current workspace's clac_ record from content.data[].uuid in the Cloud Account List or from content.uuid returned after successful creation. |
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 specify: 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.authType | string | Required on creation and only assume_role; cannot be switched on modification; do not use an old role/accessKey.Example: assume_roleHow to obtain or specify: Use the third-party AWS IAM Role authorization method. |
|
| config.area | string | Required on creation; cn/intl, 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 is unavailable for the current brand/partition. Example: intlHow to obtain or specify: Select cn for the AWS China partition and intl for the global partition; it must match the partition of the customer account and role ARN. |
|
| config.accountId | string | Required on creation and, as a business requirement, must be a string of exactly 12 digits; not a platform account ID/email/Role ARN. Changing the account is not accepted on modification; the same-named Query in the list is a fuzzy filter, do not confuse them. Example: 123456789012How to obtain or specify: Obtain the 12-digit Account ID from the customer's AWS console account information, preserving leading zeros. |
|
| config | object | Y | Required complete configuration on creation; on modification, required object; {} retains the original configuration but still validates it; dryRun=false may also resynchronize existing collection scripts. Do not include undocumented fields such as externalId/brand/workspace/long-term credentials.Allows null: False Example: {}How to obtain or specify: Construct from the customer AWS account/IAM role information and the fields below. |
| config.accountName | string | On creation, required non-empty string; if omitted on modification, retained; an empty string is rejected by business validation; maximum 256 weighted characters. Not the AWS login username or unique Account ID, and not used as a unique recovery key. Allows null: False Maximum length: 256 Example: example-accountHow to obtain or specify: A recognizable cloud account display name provided by the caller. |
|
| config.extraTags | array | Optional, up to 50 items; defaults to [] on creation; if omitted on modification, retained; [] clears them; each item can contain only key/value and both must be strings; do not add extra fields. This page manages tags and does not directly rewrite existing historical telemetry data.Allows null: False Maximum length: 50 Example: [{"key": "env", "value": "prod"}]How to obtain or specify: Tag key-value pairs that the customer chooses to attach to cloud collection data; verify the actual business naming first. |
|
| config.extraTags[*] | object | A single object must contain exactly key/value with no nulls; duplicate keys are rejected, not overridden by the last one. Example: {"key": "env", "value": "prod"}How to obtain or specify: A business tag key-value pair. |
|
| config.extraTags[*].key | string | Conditionally required | Required and non-empty; only letters/digits/_ are allowed; maximum 256 UTF-8 bytes; keys starting with __ and the reserved keys account_id/account_name are prohibited; must not be duplicated within the same array. Allows null: False Example: envHow to obtain or specify: Use a canonical business tag key. |
| config.extraTags[*].value | string | Conditionally required | Required non-empty string, maximum 1024 UTF-8 bytes; control characters and invalid surrogate characters are prohibited; numeric values must be explicitly converted to strings by the caller. Allows null: False Example: prodHow to obtain or specify: The actual value of the business tag. |
| config.roleName | string | Required on creation; if omitted on modification, retained; non-empty ASCII path/name; must not start with arn: or /, and must not end with /. The final name must be 1..64 characters and contain only letters/digits/_+=,.@-; the path follows the IAM rule of a maximum of 512 including separators, with a public total length limit of 575. Modification requires the customer-side role and trust policy to be synchronized; changing only the display name is not sufficient. Allows null: False Maximum length: 575 Example: collection/ExampleCollectorHow to obtain or specify: Obtain from the full path and role name after role/ in the customer's IAM role ARN. |
|
| dryRun | boolean | Y | Required boolean, no default. true actually calls STS but does not save the cloud account or deploy collection scripts, returning saved=false; false validates and then saves (saving is still possible when validation fails) and synchronizes existing collection scripts; this does not mean validation will necessarily pass. This parameter is not accepted on creation.Allows null: False Example: trueHow to obtain or specify: On modification, explicitly choose true for validation only or false for a formal save. |
Additional Parameter Notes¶
Only AWS assume_role records already saved in the current workspace are supported, and cloudAccount.accountManage is required. Only accountName, roleName, and extraTags can be modified; the account ID, partition, authentication type, and External ID cannot be changed through this API.
Validation and Saving¶
- After the customer Role/trust policy is configured, send
{"config":{},"dryRun":true}. The response returnssaved=falseand the validation result for this request; no database write, collection script deployment, or modification audit is performed. - Sending
dryRun=falserevalidates and saves according to the existing logic, returningsaved=trueon success. If validation fails, the account can still be saved withisAvailable=false; do not judge authorization success solely by HTTP 200. - Existing collectors are resynchronized according to the existing Front logic; retries with the same configuration may also deploy again. Idempotent account configuration saving does not equal downstream exactly-once, and a successful dryRun is not a commitment that a subsequent save will necessarily succeed.
- Omitting tags means retain;
[]clears them. RoleName supports paths and does not accept a full ARN; normal modifications retain the original External ID.
Response and Failure¶
Returns content.uuid, content.saved, content.operationResult, and content.validationResult (as well as the common content.declaration). The two result groups each carry status/code/message; operation status is completed/failed, and validation status is not_run/passed/failed. saved is null when the commit is not confirmed; for dryRun it is explicitly false, and for a successful formal save it is explicitly true. If saving/locking fails after validation has completed, the validation conclusion from this request is still retained, and HTTP retains the error status.
Non-target authentication types, cross-workspace UUIDs, or deleted UUIDs are rejected before business modification, without triggering STS, scripts, or migration. Apply capped backoff for IAM propagation delays and reuse the original UUID/External ID; on failure, query the current configuration and check the traceId, and do not blindly replace authorization identifiers.
Request Example¶
curl --request POST 'https://openapi.guance.com/api/v1/cloud_account/clac_example/do/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"config":{},"dryRun":true}'
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 | Target UUID; can be null if the pre-check of the target fails. |
| content.saved | boolean or null | False for successful dryRun, true for successful formal processing, null when formal save is unconfirmed. |
| content.operationResult | object | Operation adaptation result, completed or failed; validation failure can still be completed. |
| content.operationResult.status | string | Operation result status; as described for creationResult or operationResult. |
| content.operationResult.code | string | Operation error code, empty string on success; not the same as validationResult.code. |
| content.operationResult.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: validation not completed; passed: passed; failed: executed but not passed. |
| content.validationResult.code | string | Empty string for passed; for failed, typically ft.CloudAccountAuthInvalid or ft.CloudAccountExternalIdTrustInvalid. |
| content.validationResult.message | string | Safe business description; does not echo the raw AWS response or long-term keys. |
| content.declaration | object | Outer common declaration wrapped only on success. |
| Response Header | Type | Description |
|---|---|---|
| Cache-Control | string | no-store; successful responses and errors from this blueprint's routes are all non-cacheable. |
| Pragma | string | no-cache. |
{
"code": 200,
"content": {
"uuid": "clac_example",
"saved": false,
"operationResult": {
"status": "completed",
"code": "",
"message": ""
},
"validationResult": {
"status": "passed",
"code": "",
"message": ""
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
Error Responses¶
For authentication, rate limiting, and common request errors, see Common Error Definitions.
Failures at the public declaration/authentication layer may return 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 include a safe operation result; their internal ordinary 5xx errors uniformly return 500 ft.CodeError themselves, with content retaining the validation status from this request, and are not globally replaced with InternalServerError. Only ordinary uncaught exceptions at the temporary credential entry point go through the global 500 ft.InternalServerError. Do not rely only on HTTP or success; judge by combining the operation result, validation result, saved, and the record read back.
| HTTP Status | errorCode | Trigger Condition | Message or Response Description | Handling |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | A request field is missing, or a field value violates the declared validation conditions | Parameter parsing failed | Check the parameter location, field name, type, and value. |
| 400 | ft.RequestJsonFormatError | Request JSON syntax is invalid | 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 matches 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 to perform this operation | Check the workspace plan and management permissions; switch to a target workspace with the corresponding capabilities and authorization. |
| 404 | ft.CloudAccountNotFound | Target UUID is not in the current workspace's non-deleted cloud account scope | Cloud account does not exist | Obtain the target again from content.data[].uuid in the current workspace's AWS Role cloud account list; this read does not wait for a write lock. |
| 404 | ft.InvalidCloudAccountType | The supplied or target record is not AWS assume_role | Invalid cloud account type | Get the record from the current workspace's dedicated cloud account list; old accessKey/role and other vendors cannot be used for 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 fix it through the authorized cloud account management process, and do not pass dryRun/configuration update fields to this API. |
| 400 | ft.CloudAccountAKRepeat | Another assume_role record in the current workspace duplicates the Account ID | The current workspace already has the same {} {} |
Check the existing account; do not migrate/overwrite other records. |
| 429 | ft.OperationTooFrequently | Write lock contention/lock lost, or configuration modified by another request during waiting | Your operation is too frequent, please retry later | Before bounded backoff, read back by UUID; do not overwrite a new submission based on an old snapshot; if the creation result is unknown, recover by Account ID first. |
| 500 | ft.CodeError | An internal exception occurs while reading the cloud account/historical JSON/collector data or displaying platform authorization | Internal processing error | Retain the traceId and Query, and check the historical configuration/database and platform authorization; this read does not execute collection script deployment or configuration writes. |