Vendor Credentials End Point (AWS)

Summary

This end point is used to manage credentials within Cloudability that support the integration and ingestion of data from public cloud vendors. This includes tasks such as initial setup, listing out current credentials and deleting deprecated credentials.

This end point does not support filtering and sorting.

End Point Particulars

end point : /vendors/AWS/accounts for RESTful CRUD interactions

end point : /vendors/AWS/accounts/[vendorAccountId]/verification

end point : /vendors/AWS/accounts/[vendorAccountId]/user-to-role-migration

end point : /vendors/AWS/accounts/[vendorAccountId]/cloudformation-template

end point : /vendors/AWS/accounts/[vendorAccountId]/external-id-rotation

end point : /vendors/aws/accounts/[account_id]/archive

The Credential Object

id (string) - 12 digit string corresponding to your AWS account ID

vendorAccountName (string) - The name give to your AWS account

vendorAccountId (string) - 12 digit string corresponding to your AWS account ID

vendorKey (string) - "aws"

verification (object) - object containing details of verification state:

state (string) - examples "unverified", "verified", "error"

lastVerificationAttemptedAt (string) - date timestamp, example: "1970-01-01T00:00:00.000Z"

message (string) - error message for credentials in error state

authorization (object) - object contain vendor specific authorization details

type (string) - "aws_role" or "aws_user"

region (string) - all supported regions on AWS such as "us-west-1" or "us-west-2"

roleName (string) - currently hardcoded to "CloudabilityRole"

bucketName(string) - the name of the bucket used

externalId (string) - the external ID used to prevent confused deputies . Generated by Cloudability

parentAccountId (string) - 12 digit string representing parent's account ID (if current cred is a linked account)

createdAt - (string) - date timestamp corresponding to Cloudability credential creation time

List Accounts

curl 'https://api.cloudability.com/v3/vendors/AWS/accounts?viewId=0' \\ 
 -u ‘[auth_token]:’

{ 
"result": [ 
{ 
"id": "111111111111", 
"vendorAccountName": "AccountName", 
"vendorAccountId": "111111111111", 
"vendorKey": "aws", 
"verification": { 
"state": "verified", 
"lastVerificationAttemptedAt": "2025-12-12T05:13:40Z" 
}, 
"authorization": { 
"type": "aws_role", 
"roleName": "CloudabilityRole", 
"bucketName": "test-321", 
"externalId": "1111111c-111e-1111-1111-e1111cfc1aee", 
"costAndUsageReport": { 
"name": "test-apptio", 
"prefix": "new" 
}, 
"region": "us-east-1", 
"isOrgLevelPolicyEnabled": true, 
"turboExecutionEnabled": false, 
"applicationType": "DUAL" 
}, 
"createdAt": "2025-07-02T12:01:40Z", 
"consumerOrgId": "", 
"byodVendor": "ABSENT" 
}, 
{ 
"id": "222222222222", 
"vendorAccountName": "testlinked", 
"vendorAccountId": "222222222222", 
"vendorKey": "aws", 
"verification": { 
"state": "verified", 
"lastVerificationAttemptedAt": "2025-12-12T05:12:54Z" 
}, 
"authorization": { 
"type": "aws_role", 
"permissions": [ 
"s3:ListAllMyBuckets", 
"ec2:DescribeSnapshots" 
], 
"roleName": "CloudabilityRole_OU", 
"externalId": "d111111c-111e-1111-1111-e1111cfc1aee", 
"region": "us-east-1", 
"turboExecutionEnabled": false, 
"applicationType": "DUAL" 
}, 
"createdAt": "2025-09-22T10:02:54Z", 
"parentAccountId": "111111111111", 
"consumerOrgId": "", 
"byodVendor": "ABSENT" 
} 
] 
}

Note: If you are reviewing a master payer account you can get the payload to include all it's linked accounts by adding include=associatedAccounts as a query parameter. All linked accounts will return as a list of regular credential objects within the associatedAccounts attribute.

Create Credential for Master Payer Account

curl -X POST 'https://api.cloudability.com/v3/vendors/aws/accounts' \\ 
 -H 'Content-Type: application/json' \\ 
 -u ‘[auth_token]:’ \\ 
 -d @- << EOF 
{ 
 "vendorAccountId": "999966667777", 
 "type": "aws_role", 
 "bucketName": "some bucket name", 
 "roleName": "CloudabilityRole", 
 "externalID": "some external ID", 
 "costAndUsageReport": { 
 "name": "costandusageboth", 
 "prefix": "some prefix" 
 }, 
 "region": "us-west-2", 
 "isOrgLevelPolicyEnabled": true 
}

Upon successful creation the API will return the credentials object.

Example 'Verified' Linked Account Credentials Object

{
  "result": {
    "id": "999988887777",
    "vendorAccountName": "Account Name",
    "vendorAccountId": "999988887777",
    "vendorKey": "aws",
    "verification": {
      "state": "verified",
      "lastVerificationAttemptedAt": "2017-11-03T08:35:55.049Z"
    },
    "authorization": {
      "type": "aws_role",
      "roleName": "CloudabilityRole",
      "externalId": "1265c251-1e14-49db-b933-af3364c8ac77"
    },
    "parentAccountId": "111122223333",
    "createdAt": "2017-11-03T07:35:55.049Z"
  }
}

Create Credential for Linked Account

Special Note : If your linked account is brand new to make sure Cloudability is aware of it run a verification on your master payer account . We do have a regular background job to register new accounts, but if your account is brand new do run the verification to guarantee the credential can be created as follows.

curl -X POST 'https://api.cloudability.com/v3/vendors/aws/accounts' \\
     -H 'Content-Type: application/json' \\
     -u ‘[auth_token]:’ \\
     -d @- << EOF

{
  "vendorAccountId": "999988887777",
  "type": "aws_role"
  "region": "us-west-2"				
}
EOF

Upon successful creation the API will return the credentials object.

Note:

To ensure the API returns all accounts with these credentials requests, add viewId=0 as a URL parameter. This will ensure any default view on your user account isn't applied.

Update Credential for an Account

curl -X PUT'https://api.cloudability.com/v3/vendors/aws/accounts/[account_id]' \\ 
 -H 'Content-Type: application/json' \\ 
 -u ‘[auth_token]:’ \\ 
 -d @- << EOF 
{ 
"type": "aws_role", 
"vendorAccountId": "111111111111", 
"bucketName": "test", 
"consumerOrgId": "", 
"costAndUsageReport": { 
"name": "test", 
"prefix": "test" 
}, 
"region": "us-west-2", 
"isOrgLevelPolicyEnabled": false, 
"externalId": "c1c1a1b1-b1c1-1111-ac11-e111a11f1ab1" 
}

Upon successful update the API will return the credentials object.

Retrieve Account

curl 'https://api.cloudability.com/v3/vendors/AWS/accounts/[vendorAccountId]' \\
   -u ‘[auth_token]:’

Delete Credential for an Account

curl -X DELETE 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777' \\
     -u ‘[auth_token]:’

Verify Credentials for an Account

curl -X POST 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777/verification' \\
     -u ‘[auth_token]:’

{ 
  "result": { 
    "id": "999988887777", 
    "vendorAccountName": "Account Name", 
    "vendorAccountId": "999988887777", 
    "vendorKey": "aws", 
    "verification": { 
      "state": "verified", 
      "lastVerificationAttemptedAt": "2017-11-03T08:35:55.049Z" 
    }, 
    "authorization": { 
      "type": "aws_role", 
      "roleName": "CloudabilityRole", 
      "externalId": "1265c251-1e14-49db-b933-af3364c8ac77" 
    }, 
    "parentAccountId": "111122223333", 
    "createdAt": "2017-11-03T07:35:55.049Z" 
  } 
}

Get CloudFormation Template for Account

curl 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777/cloudformation-template' \\
     -u ‘[auth_token]:’

Rotate the External ID

 curl -X POST 'https://api.cloudability.com/v3/vendors/AWS/accounts/999988887777/external-id-rotation' \\
     -u ‘[auth_token]:’

{ 
"result": { 
"id": "string", 
"vendorAccountName": "string", 
"vendorAccountId": "string", 
"vendorKey": "string", 
"verification": { ... }, 
"authorization": { 
"type": "string", 
"permissions": ["string"], 
"roleName": "string", 
"externalId": "string", // This will contain the new rotated external ID 
"bucketName": "string", 
... 
}, 
"meta": { ... }, 
"additionalData": { ... }, 
"createdAt": "string", 
"parentAccountId": "string",
"associatedAccounts": [...], 
"customRole": boolean, 
"consumerOrgId": "string", 
"byodVendor": "string" 
} 
}

Archive Account

curl -X POST https://api.cloudability.com/v3/vendors/aws/accounts/[account_id]/archive -u ‘[auth_token]:’

Recipe for Adding New Linked Account Credentials (AWS)

If your linked account is brand new to make sure Cloudability is aware of it run a verification on your master payer account . We do have a regular background job to register new accounts, but if your account is brand new do run the verification to guarantee the credential can be created in the next step.
Create Credential For Linked Account
Get Cloudformation Template (CFT) For Account
Create CFT Stack in AWS via AWS console or AWS API/SDK/CLI (net result is the creation of the IAM role Cloudability assumes)
Verify Credentials for an account

Recipe for Migrating AWS User Creds to AWS Role Creds

Migrate a AWS User Credential to AWS Role Credential
Get Cloudformation Template (CFT) For Account
Create the CFT Stack in AWS via AWS console or AWS API/SDK/CLI
Verify Credentials for an account

Recipe for Rotating External ID

Rotate ExternalId
Update CFT Stack in AWS
Verify Credentials for an account

Recipe for Creating Credential, Retrieving External ID and Creating IAM Role with Your Own Scripting

The only unique thing about each CloudFormation template is the externalID itself. This is a AWS best practice from a security perspective, but instead of needing to generate a separate template each time you could just activate a credential, retrieve it's externalID and then script on your end to create the role. Here are the calls to do this:

Create the credential within Cloudability
The externalID is returned within the JSON response from a successful request above. It can also be obtained afterward by retrieving the account credential .
Use a script on your end to apply the externalID as a parameter with your own template.
Verify Credentials for an account