Import an AWS account into Turbot programmatically

This article will detail how to import an AWS account into Turbot using the Turbot API. 

The user with the associated Turbot access keys will need to have Turbot/ Operator at the cluster level or higher. First, it is necessary to configure the AWS account with proper IAM permissions. This can either be done using an IAM users' access keys or a role with an external ID.

AWS Configuration


  • Navigate to IAM
  • Under User, click on the Add user button
    • Provide a username
    • Under Access type, check the programmatic access box
    • In the permissions tab, select the Attach existing policies directly option
    • Select AdministratorAccess (arn:aws:iam::aws:policy/AdministratorAccess) from under the Attach existing policies directly section
    • Optional: Add tags if required
    • Review and create your new user

Note: Save the Access Key ID and the Secret Access Key that is automatically generated after the new user is created.


  • Navigate to IAM
  • Under Roles, click on Create role
  • Choose Another AWS account from the trusted entity tab
  • Provide the Account ID of your Turbot master AWS account
  • Check the Require external ID option
  • Provide an External ID of your choice
  • Select AdministratorAccess (arn:aws:iam::aws:policy/AdministratorAccess) from under the Filter policies section
  • Optional: Add tags if required
  • The next tab helps you to review this role before you create it
    • Role name: A name for the role
    • Role Description: Describe the purpose and use of the role
    • Create the role

Note: Save the Role ARN that is generated after the new role is created.

Turbot API call

POST to https://{turbotURL}/api/v3/accounts

Payload - All variables are examples and must be configured to match the organization requirements. This example is done using an external role:

"id": "$accountId",
"clusterId": "$clusterID",
"title": "$accountTitle",
"type": "awsImport",
"description": "$customDescription",
"awsRoleArn": "$roleARN",
"awsRoleExternalId": "$roleExternalId",
"deleteAwsRole": true,
"checkMode": true

Example using AWS Access Keys

type: "awsImport"
clusterId: "$clusterId"
deleteAwsKey: true
checkMode: true
id: "$accountId"
title: "$accountTitle"
awsAccessKeyId: "$userAccessKey"
$awsSecretAccessKey: "$userSecretKey"
description: "$customDescription"

The string $awsSecretAccessKey must be as shown - include the $ character. It is generally recommended that an account is imported in Check Mode, but that is at the discretion of the organization. If there are any questions regarding Check mode, reach out to Turbot support at

Once the POST is sent, it can take upwards of 5 minutes to receive a response. Verify that the account does in fact show up in the cluster, and maintenance mode can then be removed to allow Turbot to create the required resources (S3 buckets, event handlers, etc).

Was this article helpful?
0 out of 0 found this helpful