Skip to content

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

  1. Create a configuration and save the returned uuid, externalId, and platformAccountId. The first validation may fail, but the configuration can still be saved; an HTTP success does not mean AWS authorization has passed.
  2. 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. cn corresponds to aws-cn, and intl corresponds to aws; 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.
    {"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:<partition>:iam::<platformAccountId>:root"},"Action":"sts:AssumeRole","Condition":{"StringEquals":{"sts:ExternalId":"<externalId>"}}}]}
    
  3. 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, pass dryRun=false to 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.
  4. 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: created or failed; validationResult.status: not_run, passed, or failed, each carrying code/message. A single validation includes the existing probes for correct, missing, and incorrect External IDs.
  • A successful creation returns uuid, externalId, platformAccountId, and isAvailable. A failed validation can still be created; 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/role already exists for the same AWS Account ID in the same workspace, the API returns ft.CloudAccountLegacyCredentialsConflict (409) along with content.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.CloudAccountAKRepeat conflict 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; accountId is a fuzzy query, so you must iterate through pages and precisely verify config.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, the passed/failed result 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"
}