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: 123456789012How 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-accountHow 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: intlHow 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: 1How 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: 10How 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_exampleHow 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
uuidfor exact location.accountId/accountNameuse 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-levelpageInfo; records are incontent.data, andcontent.declarationfollows the Workspace declaration. - Each record retains the existing list structure, with
platformAccountIdandplatformAuthorizationStatusadded at the top level. Useconfig.externalIdto 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 isavailable, without falling back to other brands. isAvailableis a health status that may be stale. Use the modification API withdryRun=trueto perform this validation, and usedryRun=falsefor 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. |