Skip to content

Query AWS Role Cloud Accounts



GET /api/v1/cloud_account/do/list

Overview

Read AWS assume_role records in the current Workspace and the current platform authorization status in a paginated manner.

Prerequisites 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 a separate cloudAccount.temporaryCredentialsRead permission; management permissions do not automatically include it. Platform authorization is selected based on the current Workspace brand and cn/intl partition, without falling back to other brands. All responses include Cache-Control: no-store and Pragma: no-cache.

Read-only access to non-deleted AWS assume_role records in the current Workspace; provider/authType cannot be used to extend to legacy credentials or other vendors. Defaults are pageIndex=1/pageSize=10, sorted in descending order by update time (creation time if not updated); content.data is an array of rows, and pageInfo is at the top level, not in content[]. uuid provides exact filtering; accountId/accountName use fuzzy matching. To recover for writing, traverse and exactly compare the original fields.

If platform authorization is disabled or information is missing, the record and External ID are still retained, with platformAccountId=null and platformAuthorizationStatus=unavailable, without falling back to other brands. isAvailable is a historical status; use modify dryRun=true for real validation. The list neither re-validates STS nor modifies the account; it reads existing collector integration information, which does not indicate successful real-time collection.

First create the configuration and save uuid/externalId/platformAccountId. Then a customer administrator with permissions 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 be the same as the actual IAM Role path. When the Role has not been created initially, validationResult may be failed, but creationResult is still created. Continue using the same record to complete trust, then validate with modify dryRun=true, and finally save with false. Do not rotate the External ID by creating duplicates. For complete steps, see Connect an AWS Cloud Account via OpenAPI. For site endpoints, see OpenAPI Site List.

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 this operation permission from API Key Management in the target Workspace.

Query Request Parameters

Parameter Type Required Description
accountId string Optional fuzzy match; a unique match is not guaranteed. To recover creation results, compare config.accountId, area, and authType exactly page by page.
Null allowed: False
Example: 123456789012
How to obtain or enter: Obtain from the customer's AWS account information or the stored config.accountId.
accountName string Optional fuzzy match; omit to not filter. This is not the IAM role name. SQL fuzzy wildcards may affect matches; verify the original value exactly.
Null allowed: False
Example: example-account
How to obtain or enter: Keyword in the display name stored in config.accountName.
area custom_enum Optional; omit to not filter by partition. Internally compared against the stored configuration; does not switch Workspace/brand.
Null allowed: False
Optional values: ['cn', 'intl']
Example: intl
How to obtain or enter: Take cn/intl from config.area in the creation record.
pageIndex integer Optional, default 1; always use a positive integer. The public declaration does not set a unified minimum, and accepting 0/negative numbers does not guarantee valid pagination.
Null allowed: False
Example: 1
How to obtain or enter: The caller traverses starting from the first page.
pageSize integer Optional, default 10; a positive integer is recommended. The public declaration does not specify a maximum value, and the server does not impose an additional unified upper limit; avoid excessively large single requests.
Null allowed: False
Example: 10
How to obtain or enter: Choose a reasonable number based on the client's batch read requirements.
uuid string Optional exact filter for the list; if omitted, retrieves all non-deleted AWS assume_role records in the current Workspace. This is not the AWS Account ID/External ID.
Null allowed: False
Example: clac_example
How to obtain or enter: Obtain the clac_ identifier from content.data[].uuid in the Cloud Account List or from content.uuid returned after successful creation.

Additional Parameter Notes

Only AWS assume_role records in the current Workspace are returned. The cloudAccount.accountManage permission is required; having temporary credential read permission does not automatically grant access to management APIs.

  • Use uuid for exact location. accountId/accountName use fuzzy queries; when recovering creation results, compare fields exactly and traverse pagination. Page numbers start from 1, with 10 records per page by default. Pagination in the response is at the top-level pageInfo; records are in content.data, and content.declaration follows the Workspace declaration.
  • Each record retains the existing list structure, with platformAccountId and platformAuthorizationStatus added at the top level. Use config.externalId to configure the trust policy.
  • The platform account ID is the current public configuration obtained according to the current Workspace brand and record partition, not a historical identity snapshot. When unavailable, the record and External ID are retained, the platform ID is null, and the status is unavailable; normally it is available, without falling back to other brands.
  • isAvailable is a health status that may be stale. Use the modification API with dryRun=true to perform this validation, and use dryRun=false for formal saving. Subsequent retrieval of temporary credentials still performs real-time validation.
  • Does not accept provider/authType/Workspace override parameters. If the creation response is lost, query to recover first; do not regenerate the External ID.

Request Example

curl --get 'https://openapi.guance.com/api/v1/cloud_account/do/list' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  --data-urlencode pageIndex=1 \
  --data-urlencode pageSize=10 \
  --data-urlencode accountId=123456789012

Response

HTTP 200, application/json. The example below shows the main fields that can be read directly.

Field Type Description
content.data array<object> Cloud account array; empty [].
content.data[].id integer Record ID.
content.data[].uuid string clac_ cloud account UUID, used for subsequent operations.
content.data[].workspaceUUID string Owning Workspace.
content.data[].provider string Fixed to aws for this public list.
content.data[].config object Public configuration; does not return long-term credential ciphertext/plaintext.
content.data[].config.authType string assume_role.
content.data[].config.area string cn/intl partition.
content.data[].config.accountId string Customer 12-digit Account ID.
content.data[].config.roleName string Customer IAM role path/name.
content.data[].config.accountName string Configured display name.
content.data[].config.externalId string External ID of the current record, used to restore trust; not automatically rotated.
content.data[].config.extraTags array<object> Additional tags; [] if none.
content.data[].config.extraTags[].key string Tag key.
content.data[].config.extraTags[].value string Tag value.
content.data[].isAvailable integer or boolean Stored availability that may be stale; not the current real-time validation.
content.data[].status integer Status of non-deleted records; normally 0.
content.data[].creator string Creating identity.
content.data[].updator string Updating identity; empty string if not updated.
content.data[].createAt integer Creation time in Unix seconds.
content.data[].updateAt integer Update time in Unix seconds; -1 if not updated.
content.data[].deleteAt integer -1 if not deleted.
content.data[].creatorInfo object or string Identity summary; empty string if unknown. Fields may differ for account/Key/system identities.
content.data[].updatorInfo object or string Same as the creating identity summary; not a real email business card.
content.data[].integrationFileNames array<string> Names of collection integration files configured for this account; [] if none. Does not guarantee collection health.
content.data[].integrationFileNames[] string Single integration file identifier.
content.data[].platformAccountId string or null Platform ID calculated according to the current brand/partition, not a historical snapshot; null when unavailable.
content.data[].platformAuthorizationStatus string available means the platform's current configuration is available; unavailable means missing/disabled. This does not mean the customer's Role authorization has passed.
content.data[].creatorInfo.uuid string Identity UUID; may be empty for system identities.
content.data[].creatorInfo.name string Display name.
content.data[].creatorInfo.email string May be an account email, Key UUID, or system/AI label; cannot be uniformly treated as an email.
content.data[].creatorInfo.username string Login name returned conditionally.
content.data[].creatorInfo.status integer Identity status returned conditionally.
content.data[].creatorInfo.wsAccountStatus integer Workspace relationship/compatibility status returned conditionally.
content.data[].creatorInfo.iconUrl string Avatar returned conditionally.
content.data[].creatorInfo.mobile string Mobile number returned conditionally.
content.data[].creatorInfo.countryCode string Country code returned conditionally.
content.data[].creatorInfo.acntWsNickname string Workspace nickname returned conditionally.
content.data[].updatorInfo.uuid string Identity UUID; may be empty for system identities.
content.data[].updatorInfo.name string Display name.
content.data[].updatorInfo.email string May be an account email, Key UUID, or system/AI label; cannot be uniformly treated as an email.
content.data[].updatorInfo.username string Login name returned conditionally.
content.data[].updatorInfo.status integer Identity status returned conditionally.
content.data[].updatorInfo.wsAccountStatus integer Workspace relationship/compatibility status returned conditionally.
content.data[].updatorInfo.iconUrl string Avatar returned conditionally.
content.data[].updatorInfo.mobile string Mobile number returned conditionally.
content.data[].updatorInfo.countryCode string Country code returned conditionally.
content.data[].updatorInfo.acntWsNickname string Workspace nickname returned conditionally.
content.declaration object Outer Workspace declaration.
pageInfo.pageIndex integer Current page, starting from 1.
pageInfo.pageSize integer Number per page.
pageInfo.count integer Number in this page.
pageInfo.totalCount integer Total matching accounts.
Response Header Type Description
Cache-Control string no-store; caching is disabled for both successful responses and errors from this blueprint route.
Pragma string no-cache.
{
  "code": 200,
  "content": {
    "data": [
      {
        "id": 100,
        "uuid": "clac_example",
        "workspaceUUID": "wksp_example",
        "provider": "aws",
        "config": {
          "authType": "assume_role",
          "area": "intl",
          "accountId": "123456789012",
          "roleName": "collection/ExampleCollector",
          "accountName": "example-account",
          "extraTags": [
            {
              "key": "env",
              "value": "prod"
            }
          ],
          "externalId": "EXTERNAL-ID-EXAMPLE"
        },
        "isAvailable": false,
        "status": 0,
        "creator": "wsak_example",
        "updator": "",
        "createAt": 1785427200,
        "updateAt": -1,
        "deleteAt": -1,
        "creatorInfo": {},
        "updatorInfo": "",
        "integrationFileNames": [],
        "platformAccountId": "111111111111",
        "platformAuthorizationStatus": "available"
      }
    ],
    "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 only have the standard content={}; validationResult is not guaranteed to appear. After the four management entry points enter business adaptation, create/modify failures may include a safe operation result; their internal ordinary 5xx errors uniformly return 500 ft.CodeError themselves, and content retains the validation status of this request without being globally replaced by 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; determine based on the operation result, validation result, saved, and read-back record together.

HTTP Status errorCode Trigger Condition Message or Response Description Handling Method
406 ft.ParameterValidationFailed Request field is missing, or the field value violates the declared validation conditions Parameter parsing failed Check the parameter location, field name, type, and value.
403 ft.Forbidden The four management entry points are rejected by an explicit 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.
400 ft.ParamsValidateError The JSON Body is not an empty object {}, or a previously saved AWS assume_role configuration does not comply with the account/role/External ID specification Parameter validation failed: {} Submit only {} in the request. If a historical configuration is invalid, check and fix it through a cloud account management process with the required permissions; do not pass dryRun/configuration update fields in this API.
500 ft.CodeError An internal exception occurs while reading cloud accounts/historical JSON/collector information 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 deploy collection scripts or write configuration.

Feedback

Is this page helpful?