BucketDeskWorkspaceStart free trial

Admins and AWS account owners

Connect your AWS account

A connection links one S3 bucket, or one folder of it, to your workspace. It is an IAM role in your AWS account, created from BucketDesk’s CloudFormation template, that BucketDesk assumes with temporary credentials. No access keys are involved.

Only owners and admins can add, change or delete connections, and they need two-factor authentication or a passkey to do it.

Before you start#

  • The bucket name and the 12-digit ID of the AWS account that owns it.
  • Permission in that account to create a CloudFormation stack that creates IAM roles, or a colleague who has it.
  • If the bucket is encrypted with a customer-managed KMS key, the key’s ARN, and a key policy that lets the account’s IAM roles use it.
  • On Minimum, one bucket. Standard and Ultra connect any number, from several AWS accounts.

Connect a bucket#

Open Connections. In a new workspace, choose Connect your first bucket; after that, use Add connection. There are three steps.

The Connect your AWS account page of a new workspace, with an Approve in AWS button and a link to connect only one bucket or folder instead
ScreenConnections in a new workspace.

1. Choose your bucket

FieldWhat to enter
Bucket nameThe bucket exactly as S3 names it.
FolderOptional. A prefix such as marketing/assets/ limits the connection to that folder. Leave it blank to allow the whole bucket.
AWS account IDThe 12 digits of the account that owns the bucket.
Connection nameOptional. A name your team will recognise, such as Contracts.
RegionUnder Advanced AWS settings. Leave it blank to use the bucket’s own region.
Customer-managed KMS keyUnder Advanced AWS settings. Tick the box if the bucket is encrypted with your own key, and name the key.
The Connect your S3 bucket form filled in with a bucket name and an IAM role ARN, with the Features and Additional AWS settings sections closed
ScreenStep 1, filled in. The panel on the right updates to say exactly what BucketDesk will be allowed to do.

2. Approve in AWS

  1. Choose Continue to AWS to review. The CloudFormation console opens in a new tab with a stack named BucketDesk- followed by an ID, and every parameter filled in.
  2. Read the resources and permissions the stack will create.
  3. Tick the acknowledgement that the stack creates IAM resources, then choose Create stack.

If you do not have that permission yourself, choose Send to my AWS admin. BucketDesk drafts an email with the link, and your admin can use it without a BucketDesk account.

The Finish in AWS screen, showing the external ID to add to the role’s trust policy and a timer while BucketDesk checks the role
ScreenStep 2. BucketDesk waits here and checks the role every five seconds.

3. Browse your files

Back in BucketDesk, the page checks the connection every five seconds. It usually turns ready in under a minute, once the stack has finished. BucketDesk assumes the role with the connection’s external ID and reads the bucket’s versioning setting to confirm it can reach the bucket.

The Connections page with the northwind-documents bucket marked Setup required, and its details panel with Verify connection, Edit and Delete buttons
ScreenUntil the role is ready, the connection shows Setup required and a Verify connection button.

Feature switches#

A new connection is read-only. Open Do more with this bucket on the connect form to see the switches. Each one starts off. Your plan decides which switches BucketDesk accepts, and Minimum and Standard can turn on a feature above their plan while its monthly allowance lasts.

SwitchWhat it addsPlan
Unzip filesUnzips archives up to 50 GB into the bucket, on AWS Batch in your account.Standard and Ultra
Delete and recover filesDeletes, with a 30-day recycle bin inside your bucket.Ultra, or the Standard add-on
Upload filesUploads from the browser straight to the bucket, plus editing Office files.Ultra
Open archived filesRestores from S3 Glacier and Deep Archive. AWS bills each retrieval.Ultra
Ask questions about documentsDocument chat through Amazon Bedrock in your account, using a separate role.Ultra
The Features section open, showing five switches, all off: Unzip files, Delete and recover files, Upload files, Open archived files and Ask questions about documents
ScreenThe five switches, all off on a new connection.

What BucketDesk can do in your AWS account lists the exact IAM actions behind each switch.

Change a switch later

  1. On Connections, edit the connection, change the switches and save.
  2. Choose Update role in AWS. CloudFormation opens with the stack update for you to review and submit.
  3. The connection shows as pending until BucketDesk verifies the updated role.

NoteThe role changes only when you submit the update in AWS. Switching a feature off in BucketDesk and submitting the update removes its permissions from the role.

Uploads and CORS#

Browser uploads need a CORS rule on the bucket. There is nothing for you to add: when uploads are switched on, BucketDesk writes one rule named bucketdesk-uploads during verification and leaves your existing rules as they are.

Use an existing role#

If your organisation creates IAM roles its own way, choose Use an existing role under Advanced AWS settings instead of the guided setup.

Additional AWS settings open, showing optional Folder, Connection name and AWS region fields and a checkbox for a customer-managed KMS key
ScreenAdditional AWS settings: the folder, the connection name, the region and the KMS key checkbox.
  1. Paste the role’s ARN.
  2. Add the external ID that BucketDesk shows to the role’s trust policy.
  3. Verify the connection.

You then maintain the role’s permissions yourself. The action lists on the AWS access page show what each feature needs.

What cannot be changed#

Once the stack exists, a connection’s AWS account, region and setup method are fixed. To change any of them, add a new connection and delete the old one.

Tools install their own stacks#

S3 Savings, Storage and Websites are installed per AWS account from the Tools page, each with its own CloudFormation stack and role, separate from your bucket connections.

  1. Open the tool on the Tools page and enter the AWS account ID and which buckets it may reach.
  2. Choose Deploy stack in AWS, review it and create the stack.
  3. Back in BucketDesk, choose Check the stack.
The Tools page listing Convert, Transfers, S3 Savings, Storage overview and Websites, each with a Set up or Open link, and S3 Savings open in a side panel
ScreenThe Tools page. Each tool installs through its own stack.
ToolWhat it doesPlan
S3 SavingsA free, read-only assessment of what the account pays for S3 and what each change would save. Applying changes is charged as a share of verified savings.Every plan
StorageSize, cost and growth for each AWS account.Every plan
WebsitesPublishes a bucket folder as a website through CloudFront in your account.Standard and Ultra

Owners and admins install tools.

Troubleshooting#

MessageWhat to check
AWS could not verify this role. Check that the stack finished and its external ID matches.Wait for the stack to reach CREATE_COMPLETE. If you edited the stack’s parameters by hand, open the link from BucketDesk again so the external ID matches.
The configured bucket does not exist or is not visible to this role.Check the bucket name for typos and that the bucket is in the AWS account you entered.
AWS denied this operation. Review the role policy and selected scope.The file is outside the connection’s folder, the feature is not switched on in the stack, or a bucket policy or KMS key policy denies the role.
The deployed stack is from another release. Update it from the link on this page, then verify again.BucketDesk’s template has changed since the stack was created. Use Update role in AWS and submit the update.
The stack in AWS uses different settings than this page.The switches saved in BucketDesk and the stack’s parameters disagree. Submit the stack update from the connection, or change the switches back.
AWS is temporarily throttling requests. Try again shortly.Wait a moment and retry. Nothing needs changing.
S3 refused this upload from the browser.The bucket’s upload CORS rule is missing. An admin should update the connection’s stack in AWS and verify the connection again.
Files in an encrypted bucket fail to open or upload.A customer-managed KMS key whose key policy does not allow the role returns AccessDenied. Allow the role in the key policy, and make sure the key is named on the connection.

Disconnect and remove access#

  1. On Connections, choose Delete connection. BucketDesk names the stack or role to remove in AWS.
  2. In the CloudFormation console, delete that BucketDesk- stack.

Your S3 files are not changed. BucketDesk erases the role details at once and deletes the rest of the connection’s record 30 days later. If ZIP extraction was on, its scratch bucket stays behind for you to delete; its contents expire within 7 days.

NoteDeleting the stack is what ends access. You can do it at any time, with or without deleting the connection in BucketDesk first: the role goes with the stack and BucketDesk’s next request is refused.

Something wrong or missing on this page? Email info@bucketdesk.com. Last updated November 12, 2026.

Let's chat

Questions? Message directly.