Skip to content

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 return saved=false and the validation result of this run. No database write occurs, no collection script is delivered, and no modification audit is generated.
  • Passing dryRun=false revalidates and saves according to the existing logic, returning saved=true on success. If validation fails, the record can still be saved with isAvailable=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"
}