Skip to content

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: 123456789012
How 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-account
How 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: intl
How 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_role
How 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: env
How 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: prod
How 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/ExampleCollector
How 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: aws
How 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

  1. Create the configuration and save the returned uuid, externalId, and platformAccountId. The first validation may fail, but the configuration can still be saved; HTTP success does not mean AWS authorization has passed.
  2. 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. 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 customer AWS resources on the customer's behalf and does not accept customer 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 deployment is complete, call the modify API {"config":{},"dryRun":true} to validate; after it passes, pass dryRun=false to 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.
  4. 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: created or failed; validationResult.status: not_run, passed, or failed, each carrying code/message. One validation includes the original correct/missing/incorrect External ID probes.
  • Successful creation returns uuid, externalId, platformAccountId, and isAvailable. A validation failure can also be created; 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, return ft.CloudAccountLegacyCredentialsConflict (409) and content.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.CloudAccountAKRepeat conflict and the existing record UUID, and does not automatically modify or replace. After a network timeout/5xx, first recover the record via list; accountId is a fuzzy query, so you must paginate and accurately verify config.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, this passed/failed is 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.

Feedback

Is this page helpful?