AWS Accounts

Docs > Cloudcraft > Cloudcraft API Reference > AWS Accounts

List AWS accounts

GET /aws/account

Overview

List all AWS accounts linked to your Cloudcraft account.

The response is an array of AWS accounts. Each entry includes the account ID and name, access control, and user information.

The provided account IDs are required to access the other AWS-related APIs.

Response

Expand All

Field

Type

Description

accounts

array

An array of AWS accounts.

{
  "accounts": [
    {
      "CreatorId": "us46e9aa-5806-4cd6-8e78-c22d58602d09",
      "createdAt": "2022-01-01T21:18:59.057Z",
      "externalId": "ex53e827-a724-4a2a-9fec-b13761540785",
      "id": "awfda35c-82fe-4edf-b9e9-ffd48f041c22",
      "name": "Development",
      "roleArn": "arn:aws:iam::1234567890:role/cloudcraft",
      "updatedAt": "2022-01-01T21:19:03.487Z"
    }
  ]
}

Unauthorized

Code Example

curl --location 'https://api.cloudcraft.co/aws/account'

package main

import (
	"context"
	"log"
	"os"

	"github.com/DataDog/cloudcraft-go"
)

func main() {
	// Get the API key from the environment.
	key, ok := os.LookupEnv("CLOUDCRAFT_API_KEY")
	if !ok {
		log.Fatal("missing env var: CLOUDCRAFT_API_KEY")
	}

	// Create new Config to initialize a Client.
	cfg := cloudcraft.NewConfig(key)

	// Create a new Client instance with the given Config.
	client, err := cloudcraft.NewClient(cfg)
	if err != nil {
		log.Fatal(err)
	}

	// List all AWS accounts in the Cloudcraft account.
	accounts, _, err := client.AWS.List(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Print the name of each account.
	for _, account := range accounts {
		log.Println(account.Name)
	}
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.cloudcraft.co/aws/account")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

from cloudcraftco import Cloudcraft

cloudcraft = Cloudcraft()

accounts = cloudcraft.list_aws_accounts()

require "uri"
require "net/http"

url = URI("https://api.cloudcraft.co/aws/account")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)

response = https.request(request)
puts response.read_body

var requestOptions = {
  method: 'GET',
  redirect: 'follow'
};

fetch("https://api.cloudcraft.co/aws/account", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Add an AWS account

POST /aws/account

Overview

The body of the request should contain the account properties in JSON format. The response contains the created account object, including the newly assigned ID for use with other API endpoints.

Properties

name: A human-readable name for the AWS account. For example, “Production” or “Staging”.
roleArn: The ARN of the read-only IAM role you’ve created in your AWS account for Cloudcraft. The IAM role must be created with the unique external ID value of the person who generated the API key being used.
region: Optional property representing the AWS region to be used for account validation. By default, the account will be validated in the us-east-1 region.

Response

Expand All

Field

Type

Description

CreatorId

string

The user ID of the creator of the AWS account.

createdAt

string

The date and time the AWS account was created.

externalId

string

The unique external ID of the Cloudcraft user who created the AWS account.

string

The unique identifier of the AWS account.

name

string

A human-readable name for the AWS account.

roleArn

string

The ARN of the IAM role created in AWS for Cloudcraft.

updatedAt

string

The date and time the AWS account was last updated.

{
  "CreatorId": "us46e9aa-5806-4cd6-8e78-c22d58602d09",
  "createdAt": "2022-01-01T01:37:55.709Z",
  "externalId": "ex53e827-a724-4a2a-9fec-b13761540785",
  "id": "awfda35c-82fe-4edf-b9e9-ffd48f041c22 ",
  "name": "AWS account name (for example prod or staging)",
  "roleArn": "arn:aws:iam::1234567890:role/cloudcraft",
  "updatedAt": "2022-01-01T01:37:55.709Z"
}

Unauthorized

Forbidden, insufficient privileges

Code Example

curl --location 'https://api.cloudcraft.co/aws/account' \
--header 'Content-Type: application/json' \
--data '{"name": "AWS account name (for example, prod or staging)",
"roleArn": "arn:aws:iam::1234567890:role/cloudcraft",
}'

package main

import (
	"context"
	"log"
	"os"

	"github.com/DataDog/cloudcraft-go"
)

func main() {
	// Get the API key from the environment.
	key, ok := os.LookupEnv("CLOUDCRAFT_API_KEY")
	if !ok {
		log.Fatal("missing env var: CLOUDCRAFT_API_KEY")
	}

	// Check if the command line arguments are correct.
	if len(os.Args) != 3 {
		log.Fatalf("usage: %s <account-name> <role-arn>", os.Args[0])
	}

	// Create new Config to initialize a Client.
	cfg := cloudcraft.NewConfig(key)

	// Create a new Client instance with the given Config.
	client, err := cloudcraft.NewClient(cfg)
	if err != nil {
		log.Fatal(err)
	}

	// Create a new AWS Account with the name and role ARN coming from command
	// line arguments.
	account, _, err := client.AWS.Create(
		context.Background(),
		&cloudcraft.AWSAccount{
			Name:    os.Args[1],
			RoleARN: os.Args[2],
		})
	if err != nil {
		log.Fatal(err)
	}

	// Print the account ID.
	log.Println(account.ID)
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"name\": \"AWS account name (for example prod or staging)\",\n    \"roleArn\": \"arn:aws:iam::1234567890:role/cloudcraft\"\n}\n");
Request request = new Request.Builder()
  .url("https://api.cloudcraft.co/aws/account")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

from cloudcraftco import Cloudcraft

cloudcraft = Cloudcraft()

data = {"name": "AWS Account.", "roleArn": 'your-role-arn'}
result = cloudcraft.create_aws_account(data)

require "uri"
require "json"
require "net/http"

url = URI("https://api.cloudcraft.co/aws/account")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "name": "AWS account name (for example, prod or staging)",
"roleArn": "arn:aws:iam::1234567890:role/cloudcraft",

})

response = https.request(request)
puts response.read_body

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  HERE"name": "AWS account name (for example, prod or staging)",
"roleArn": "arn:aws:iam::1234567890:role/cloudcraft",

});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.cloudcraft.co/aws/account", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Get AWS IAM role parameters

GET /aws/account/iamParameters

Overview

List the parameters required for you to register a new IAM role in AWS for use with Cloudcraft.

Combined with the AWS CLI to generate IAM roles, this endpoint can facilitate fully automated role creation at scale for organizations with many AWS accounts.

Response

Expand All

Field

Type

Description

accountId

string

The AWS account ID for Cloudcraft.

awsConsoleUrl

string

The URL to the AWS IAM console with pre-filled role creation parameters.

externalId

string

The unique external ID for the Cloudcraft user.

{
  "accountId": "1234567890",
  "awsConsoleUrl": "https://console.aws.amazon.com/iam/home?#/roles...",
  "externalId": "ex53e827-a724-4a2a-9fec-b13761540785"
}

Unauthorized

Code Example

curl --location 'https://api.cloudcraft.co/aws/account/iamParameters'

package main

import (
	"context"
	"encoding/json"
	"log"
	"os"

	"github.com/DataDog/cloudcraft-go"
)

func main() {
	// Get the API key from the environment.
	key, ok := os.LookupEnv("CLOUDCRAFT_API_KEY")
	if !ok {
		log.Fatal("missing env var: CLOUDCRAFT_API_KEY")
	}

	// Create new Config to initialize a Client.
	cfg := cloudcraft.NewConfig(key)

	// Create a new Client instance with the given Config.
	client, err := cloudcraft.NewClient(cfg)
	if err != nil {
		log.Fatal(err)
	}

	// Get the IAM parameters required for registering a new IAM Role in AWS for
	// use with Cloudcraft.
	params, _, err := client.AWS.IAMParameters(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	// Pretty print all IAM parameters returned by the API.
	pretty, _ := json.MarshalIndent(params, "", "  ")

	log.Println(string(pretty))
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.cloudcraft.co/aws/account/iamParameters")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

from cloudcraftco import Cloudcraft

cloudcraft = Cloudcraft()

params = cloudcraft.read_aws_role_parameters()

require "uri"
require "net/http"

url = URI("https://api.cloudcraft.co/aws/account/iamParameters")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)

response = https.request(request)
puts response.read_body

var requestOptions = {
  method: 'GET',
  redirect: 'follow'
};

fetch("https://api.cloudcraft.co/aws/account/iamParameters", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Delete AWS account

DELETE /aws/account/{account_id}

Overview

Delete a registered AWS account.

Path Parameters

account_id: UUID. AWS account ID. Required.

Response

Unauthorized

Forbidden, insufficient privileges

AWS account not found

Code Example

curl --location --request DELETE 'https://api.cloudcraft.co/aws/account/{account_id}'

package main

import (
	"context"
	"log"
	"os"

	"github.com/DataDog/cloudcraft-go"
)

func main() {
	// Get the API key from the environment.
	key, ok := os.LookupEnv("CLOUDCRAFT_API_KEY")
	if !ok {
		log.Fatal("missing env var: CLOUDCRAFT_API_KEY")
	}

	// Show usage if the number of command line arguments is not correct.
	if len(os.Args) != 2 {
		log.Fatalf("usage: %s <account-id>", os.Args[0])
	}

	// Create new Config to initialize a Client.
	cfg := cloudcraft.NewConfig(key)

	// Create a new Client instance with the given Config.
	client, err := cloudcraft.NewClient(cfg)
	if err != nil {
		log.Fatal(err)
	}

	// Delete the AWS account with the ID taken from a command line argument.
	_, err = client.AWS.Delete(
		context.Background(),
		os.Args[1],
	)
	if err != nil {
		log.Fatal(err)
	}
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.cloudcraft.co/aws/account/{account_id}")
  .method("DELETE", body)
  .build();
Response response = client.newCall(request).execute();

from cloudcraftco import Cloudcraft

cloudcraft = Cloudcraft()

account_id = 'your account id'
result = cloudcraft.delete_aws_account(account_id)

require "uri"
require "net/http"

url = URI("https://api.cloudcraft.co/aws/account/{account_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = https.request(request)
puts response.read_body

var requestOptions = {
  method: 'DELETE',
  redirect: 'follow'
};

fetch("https://api.cloudcraft.co/aws/account/{account_id}", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Update an AWS account

PUT /aws/account/{account_id}

Overview

Update an AWS account registered in Cloudcraft.

The body of the request should contain the account properties in JSON format. The response contains the updated account object.

Properties

name: A human-readable name for the AWS account. For example, “Production” or “Staging”.
roleArn: The ARN of the read-only IAM role you’ve created in your AWS account for Cloudcraft. The IAM role must be created with the unique external ID value of the person who generated the API key being used.

Response

Unauthorized

Forbidden, insufficient privileges

Code Example

curl --location --request PUT 'https://api.cloudcraft.co/aws/account/{account_id}' \
--data '{"name": "My updated AWS Account",
"roleArn": "arn:aws:iam::1234567890:role/cloudcraft",
}'

package main

import (
	"context"
	"log"
	"os"

	"github.com/DataDog/cloudcraft-go"
)

func main() {
	// Get the API key from the environment.
	key, ok := os.LookupEnv("CLOUDCRAFT_API_KEY")
	if !ok {
		log.Fatal("missing env var: CLOUDCRAFT_API_KEY")
	}

	// Check if the command line arguments are correct.
	if len(os.Args) != 4 {
		log.Fatalf("usage: %s <account-id> <account-name> <role-arn>", os.Args[0])
	}

	// Create new Config to initialize a Client.
	cfg := cloudcraft.NewConfig(key)

	// Create a new Client instance with the given Config.
	client, err := cloudcraft.NewClient(cfg)
	if err != nil {
		log.Fatal(err)
	}

	// Update the AWS Account with the ID, name and role ARN coming from command
	// line arguments.
	_, err = client.AWS.Update(
		context.Background(),
		&cloudcraft.AWSAccount{
			ID:      os.Args[1],
			Name:    os.Args[2],
			RoleARN: os.Args[3],
		})
	if err != nil {
		log.Fatal(err)
	}
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "{\n    \"name\": \"My updated AWS Account\",\n    \"roleArn\": \"arn:aws:iam::1234567890:role/cloudcraft\"\n}\n");
Request request = new Request.Builder()
  .url("https://api.cloudcraft.co/aws/account/{account_id}")
  .method("PUT", body)
  .build();
Response response = client.newCall(request).execute();

from cloudcraftco import Cloudcraft

cloudcraft = Cloudcraft()

account_id = 'your account id'
data = {"name": "Updated AWS Account.", "roleArn": 'your-role-arn'}
result = cloudcraft.update_aws_account(account_id, data)

require "uri"
require "net/http"

url = URI("https://api.cloudcraft.co/aws/account/{account_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Put.new(url)
request.body = "{\n    \"name\": \"My updated AWS Account\",\n    \"roleArn\": \"arn:aws:iam::1234567890:role/cloudcraft\"\n}\n"

response = https.request(request)
puts response.read_body

var raw = "{\n    \"name\": \"My updated AWS Account\",\n    \"roleArn\": \"arn:aws:iam::1234567890:role/cloudcraft\"\n}\n";

var requestOptions = {
  method: 'PUT',
  body: raw,
  redirect: 'follow'
};

fetch("https://api.cloudcraft.co/aws/account/{account_id}", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Snapshot AWS account

GET /aws/account/{account_id}/{region}/{format}

Overview

Scan and render one region of an AWS account into a blueprint in JSON, SVG, PNG, PDF, or MxGraph format.

The time required to generate the snapshot depends on the number of resources in the AWS region.

The API behaves as a long poll, with a wait time of up to 120 seconds for the result. For most
environments, the API call will therefore directly return a blueprint. If
the wait time is exceeded, a 202 Accepted response is returned with a
{code: STILL_PROCESSING, retry: true ...} JSON body. The snapshot will continue processing in the background, and a retry will either immediately return the result or continue waiting.

Path Parameters

account_id: UUID. The AWS account ID as registered with Cloudcraft.
region: String. The AWS region, for example, “us-east-1”.
format: String. One of “json”, “svg”, “png”, “pdf”, “mxGraph”.

Optional query parameters

filter: String. Render a subset of the AWS account. Accepts a filter expression as used on the Live tab in the web application. The filter expression terms must be separated by spaces. The terms are substrings to be matched, key-value pairs, logical operators, or parentheses. For example, `env=dev OR env=test`.
exclude: List of Strings. Exclude AWS services by name. For example, “ec2,sg” to exclude both EC2s and Security Groups. The service value is specified by the “type” field of Blueprint components.
label: Boolean. Automatically label all components. Defaults to true.
autoconnect: Boolean. Automatically connect all components. Defaults to true.
scale: Float. Scale relative to original size (1.0). For example, 0.5 for half or 2.0 for double size.
width: Number. Image width in pixels (for SVG, PNG, and PDF).
height: Number. Image height in pixels (for SVG, PNG, and PDF).
grid: Boolean. Enable or disable grid rendering.
transparent: Boolean. Enable or disable transparent background rendering.
landscape: Boolean. Enable or disable landscape paper format (PDF).
paperSize: String. Applies when the format is PDF. One of “Letter”, “Legal”, “Tabloid”, “Ledger”, “A0”, “A1”, “A2”, “A3”, “A4”, or “A5”.
projection: String. The visual style of the diagram. One of “isometric” or “2d”.
theme: String. The color theme of the diagram. One of “light” or “dark”.

Response

Wait time exceeded

Expand All

Field

Type

Description

code

string

A code indicating the status of the snapshot generation.

message

string

A message explaining the reason for the 202 response.

retry

boolean

A flag indicating whether the client should retry the request.

{
  "code": "STILL_PROCESSING",
  "message": "Result wait time exceeded. Processing continues in the background, retry to receive result.",
  "retry": true
}

Unauthorized

Forbidden, insufficient privileges

AWS account not found

Code Example

curl --location 'https://api.cloudcraft.co/aws/account/{account_id}/{region}/{format}'

package main

import (
	"context"
	"log"
	"os"

	"github.com/DataDog/cloudcraft-go"
)

func main() {
	// Get the API key from the environment.
	key, ok := os.LookupEnv("CLOUDCRAFT_API_KEY")
	if !ok {
		log.Fatal("missing env var: CLOUDCRAFT_API_KEY")
	}

	// Check if the command line arguments are correct.
	if len(os.Args) != 2 {
		log.Fatalf("usage: %s <account-id>", os.Args[0])
	}

	// Create new Config to initialize a Client.
	cfg := cloudcraft.NewConfig(key)

	// Create a new Client instance with the given Config.
	client, err := cloudcraft.NewClient(cfg)
	if err != nil {
		log.Fatal(err)
	}

	// Create a new snapshot of the us-east-1 region with the given account-id
	// coming from a command line argument.
	snapshot, _, err := client.AWS.Snapshot(
		context.Background(),
		os.Args[1],
		"us-east-1",
		"png",
		&cloudcraft.SnapshotParams{
			Width:  1920,
			Height: 1080,
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	// Save the snapshot to a file.
	if err := os.WriteFile("snapshot.png", snapshot, 0o600); err != nil {
		log.Fatal(err)
	}
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.cloudcraft.co/aws/account/{account_id}/{region}/{format}")
  .method("GET", body)
  .build();
Response response = client.newCall(request).execute();

from cloudcraftco import Cloudcraft

cloudcraft = Cloudcraft()

account_id = 1234
options = {"grid": True, "scale": 1.5}
region = "us-east-1"
file_format = "png"
snapshot = cloudcraft.snapshot_aws_account(account_id, region, file_format, options)
with open(f'snapshot.{file_format}', "wb") as binary_file:
    binary_file.write(snapshot)

require "uri"
require "net/http"

url = URI("https://api.cloudcraft.co/aws/account/{account_id}/{region}/{format}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)

response = https.request(request)
puts response.read_body

var requestOptions = {
  method: 'GET',
  redirect: 'follow'
};

fetch("https://api.cloudcraft.co/aws/account/{account_id}/{region}/{format}", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));