AWS accounts

The awsAccounts resource manages bring-your-own AWS connections — provisioning the cross-account role, validating it, importing existing S3 buckets into Buckt, and disconnecting accounts when retired.

connect

awsAccounts.connectPOST/v1/aws-accounts

awsAccounts.connect(opts?: {
  label?: string;
}): Promise<WriteResponse<"aws_account">>

Creates a new account record and returns its id. The account starts in pending status — deploy the CloudFormation template, then call validate() to flip it to active.

Name	Type	Default	Description
label	string	—	Human-readable name shown in the dashboard. Optional but recommended when connecting multiple accounts.

const { id } = await client.awsAccounts.connect({ label: "production" });

// `id` is the Buckt-side account record. Deploy the CloudFormation
// template displayed in the dashboard to grant Buckt the IAM role.
console.log(id);

{
  "object": "aws_account",
  "id": "awa_01H8XYZABCDEFGHJKMNPQRSTVW"
}

list

awsAccounts.listGET/v1/aws-accounts

awsAccounts.list(opts?: {
  cursor?: string;
  limit?: number;
}): Promise<{ data: AwsAccount[]; meta: CursorMeta }>

Lists connected AWS accounts. Cursor-paginated.

Name	Type	Default	Description
cursor	string	—	Opaque cursor returned from a previous call. Omit for the first page.
limit	number	25	Page size. Maximum 100.

const { data, meta } = await client.awsAccounts.list({ limit: 50 });

for (const account of data) {
  console.log(account.id, account.awsAccountId, account.status);
}

{
  "data": [
    {
      "object": "aws_account",
      "id": "awa_01H8XYZABCDEFGHJKMNPQRSTVW",
      "awsAccountId": "111122223333",
      "externalId": "ext_aBcD1234",
      "roleArn": "arn:aws:iam::111122223333:role/BucktAccessRole",
      "stackId": "arn:aws:cloudformation:us-east-1:111122223333:stack/Buckt/abc123",
      "label": "production",
      "status": "active",
      "lastValidatedAt": "2026-04-25T12:34:56Z",
      "createdAt": "2026-03-01T08:00:00Z",
      "updatedAt": "2026-04-25T12:34:56Z"
    }
  ],
  "meta": { "limit": 25, "nextCursor": null }
}

get

awsAccounts.getGET/v1/aws-accounts/{id}

awsAccounts.get(id: string): Promise<AwsAccount>

Fetches a single account, including the CloudFormation stack id and last-validated timestamp.

const account = await client.awsAccounts.get(
  "awa_01H8XYZABCDEFGHJKMNPQRSTVW"
);

console.log(account.status, account.lastValidatedAt);

{
  "object": "aws_account",
  "id": "awa_01H8XYZABCDEFGHJKMNPQRSTVW",
  "awsAccountId": "111122223333",
  "externalId": "ext_aBcD1234",
  "roleArn": "arn:aws:iam::111122223333:role/BucktAccessRole",
  "stackId": "arn:aws:cloudformation:us-east-1:111122223333:stack/Buckt/abc123",
  "label": "production",
  "status": "active",
  "lastValidatedAt": "2026-04-25T12:34:56Z",
  "createdAt": "2026-03-01T08:00:00Z",
  "updatedAt": "2026-04-25T12:34:56Z"
}

update

awsAccounts.updatePATCH/v1/aws-accounts/{id}

awsAccounts.update(id: string, opts: {
  roleArn?: string;
  stackId?: string;
  label?: string;
}): Promise<WriteResponse<"aws_account">>

Updates the account's label, IAM role ARN, or CloudFormation stack id. Useful after redeploying the role with extra permissions.

Name	Type	Default	Description
roleArn	string	—	Updated IAM role ARN that Buckt assumes for S3 operations.
stackId	string	—	Updated CloudFormation stack id (only relevant if you redeployed the stack).
label	string	—	Updated display name.

await client.awsAccounts.update("awa_01H8XYZABCDEFGHJKMNPQRSTVW", {
  label: "staging",
  roleArn: "arn:aws:iam::111122223333:role/BucktAccessRole",
});

{
  "object": "aws_account",
  "id": "awa_01H8XYZABCDEFGHJKMNPQRSTVW"
}

validate

awsAccounts.validatePOST/v1/aws-accounts/{id}/validate

awsAccounts.validate(id: string): Promise<WriteResponse<"aws_account">>

Re-runs the AssumeRole + permission probe against the connected account. On success, transitions pending/failed to active and refreshes lastValidatedAt. Throws ValidationError with the underlying AWS error message on failure.

await client.awsAccounts.validate("awa_01H8XYZABCDEFGHJKMNPQRSTVW");

{
  "object": "aws_account",
  "id": "awa_01H8XYZABCDEFGHJKMNPQRSTVW"
}

disconnect

awsAccounts.disconnectDELETE/v1/aws-accounts/{id}

awsAccounts.disconnect(id: string): Promise<WriteResponse<"aws_account">>

Removes the Buckt-side record for the account. The CloudFormation stack in your AWS account is left in place — delete it manually to revoke Buckt's IAM access. Throws ConflictError if any imported buckets still reference this account.

await client.awsAccounts.disconnect(
  "awa_01H8XYZABCDEFGHJKMNPQRSTVW"
);

{
  "object": "aws_account",
  "id": "awa_01H8XYZABCDEFGHJKMNPQRSTVW"
}

listS3Buckets

awsAccounts.listS3BucketsGET/v1/aws-accounts/{id}/s3-buckets

awsAccounts.listS3Buckets(id: string, opts?: {
  cursor?: string;
  limit?: number;
}): Promise<{ data: S3BucketInfo[]; meta: CursorMeta }>

Lists every S3 bucket Buckt can see in the connected account — used to populate the import picker. Cursor-paginated.

Name	Type	Default	Description
cursor	string	—	Opaque cursor returned from a previous call. Omit for the first page.
limit	number	25	Page size. Maximum 100.

const { data } = await client.awsAccounts.listS3Buckets(
  "awa_01H8XYZABCDEFGHJKMNPQRSTVW",
  { limit: 100 }
);

for (const bucket of data) {
  console.log(bucket.id, bucket.creationDate);
}

{
  "data": [
    {
      "object": "s3_bucket",
      "id": "legacy-marketing",
      "creationDate": "2024-06-12T00:00:00Z"
    }
  ],
  "meta": { "limit": 25, "nextCursor": null }
}

importBuckets

awsAccounts.importBucketsPOST/v1/aws-accounts/{id}/import

awsAccounts.importBuckets(id: string, opts: {
  bucketNames: string[];
}): Promise<WriteResponse<"bucket">[]>

Imports existing S3 buckets in the connected account as Buckt-managed buckets. The S3 buckets are not copied — Buckt manages them in place via the CloudFormation role.

Name	Type	Default	Description
bucketNamesrequired	string[]	—	Names of S3 buckets in the connected account to import as Buckt-managed buckets. Each must already exist.

const imported = await client.awsAccounts.importBuckets(
  "awa_01H8XYZABCDEFGHJKMNPQRSTVW",
  { bucketNames: ["legacy-marketing", "legacy-product"] }
);

for (const result of imported) {
  console.log(result.id);
}

[
  { "object": "bucket", "id": "bkt_01H8XYZABCDEFGHJKMNPQRSTVW" },
  { "object": "bucket", "id": "bkt_01H8XYZABCDEFGHJKMNPQRSTVX" }
]