Modify or Validate an AWS Role Cloud Account¶
POST /api/v1/cloud_account/{cloud_account_uuid}/do/modify
Route Parameters¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| cloud_account_uuid | string | Y | Cloud account UUID Allow empty string: False |
Body Request Parameters¶
| Parameter Name | Type | Required | Description |
|---|---|---|---|
| config | object | Y | Configuration Allow empty: False |
| config.roleName | string | Authorized role name or path (assume_role supports paths; the legacy role keeps its original restriction) Example: string Maximum length: 575 Allow empty: False |
|
| config.accountName | string | Username Example: string Maximum length: 256 Allow empty: False |
|
| config.extraTags | array | Cloud account tags; up to 50 items. Omit on edit to keep existing tags; an empty array clears them Maximum length: 50 Allow empty: False |
|
| config.extraTags[*] | object | ||
| config.extraTags[*].key | string | Y | Allow empty: False |
| config.extraTags[*].value | string | Y | Allow empty: False |
| dryRun | boolean | Y | Whether to only validate account availability; true does not persist, false performs the save. Callers must pass a value explicitly Example: True Allow empty: False |
Additional Parameter Notes¶
For end-to-end steps, see Access an AWS Cloud Account via OpenAPI. The Endpoint in the examples is taken from the OpenAPI Site List.
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's Role/trust policy is configured, pass
{"config":{},"dryRun":true}to returnsaved=falseand the validation result of this run. No database write occurs, no collection script is delivered, and no modification audit is generated. - Passing
dryRun=falserevalidates and saves according to the existing logic, returningsaved=trueon success. If validation fails, the record can still be saved withisAvailable=false; do not determine authorization success solely from HTTP 200. - Existing collectors resync according to the current Front logic; retries with the same configuration may also be delivered again. Idempotent account configuration saving does not equal downstream exactly-once, and a successful dryRun is not a promise that subsequent saves will succeed.
- Omitting tags keeps them;
[]clears them. RoleName supports paths and does not accept a full ARN; a normal modification keeps the original External ID.
Responses and Failures¶
Returns content.uuid, content.saved, content.operationResult, and content.validationResult (plus the common content.declaration). The two result sets each carry status/code/message; the operation status is completed/failed, and the validation status is not_run/passed/failed. saved is null when the commit is not confirmed, explicitly false for dryRun, and explicitly true on a successful formal save. If saving/locking fails after validation has completed, the validation conclusion from this run is retained, and the HTTP status is preserved as an error.
Non-target authentication types, cross-workspace, or deleted UUIDs are rejected before any business modification, without triggering STS, scripts, or migration. Bounded backoff is applied for IAM propagation delays, reusing the original UUID/External ID; on failure, query the current configuration and verify the traceId rather than blindly replacing the authorization identifier.
Request Example¶
curl -X POST '<Endpoint>/api/v1/cloud_account/<cloud_account_uuid>/do/modify' -H 'DF-API-KEY: <DF-API-KEY>' -H 'Content-Type: application/json' --data-raw '{"config": {}, "dryRun": true}'
Response¶
{
"code": 200,
"success": true,
"errorCode": "",
"message": "",
"content": {
"uuid": "clac_example",
"saved": false,
"operationResult": {
"status": "completed",
"code": "",
"message": ""
},
"validationResult": {
"status": "passed",
"code": "",
"message": ""
},
"declaration": {}
},
"traceId": "TRACE-example"
}