# AWS S3

> Connect AWS S3 to BucketMate with access keys, AWS profiles, or AWS SSO

Canonical: https://docs.bucketmate.app/macos/providers/connect-aws-s3

BucketMate can connect to AWS S3 with static access keys, local AWS profiles, or AWS SSO profiles from your Mac.

## Prerequisites

- AWS Account
- Access Key ID and Secret Access Key, or a profile in `~/.aws/config` or `~/.aws/credentials`
- S3 bucket access
- Region for the bucket you want to manage

## Recommended IAM permissions

Start with the narrowest policy that matches your workflow. BucketMate features can require these S3 actions:

- `s3:ListAllMyBuckets` to load all buckets automatically
- `s3:ListBucket` to browse a bucket
- `s3:GetObject` to download, preview, open, and share files
- `s3:PutObject` to upload, create folders, rename, move, and quick edit
- `s3:DeleteObject` to delete, rename, move, and empty buckets
- `s3:CreateBucket` to create buckets
- `s3:DeleteBucket` to delete empty buckets

If you do not allow `s3:ListAllMyBuckets`, turn off **Credentials have permission to list buckets** and enter bucket names manually.

## Connection steps

### Access key

1. Open BucketMate.
2. Choose **Add Connection**.
3. Select **AWS S3**.
4. Select **Access Key**.
5. Leave endpoint empty, or enter `https://s3.<region>.amazonaws.com`.
6. Enter the access key ID and secret access key.
7. Select the bucket region.
8. Use **Test Connection**.
9. Save the connection.

### AWS profile

1. Configure an AWS profile with the AWS CLI.
2. Open BucketMate.
3. Choose **Add Connection**.
4. Select **AWS S3**.
5. Select **AWS Profile**.
6. Choose a detected profile.
7. For SSO profiles, use **Login with SSO** and finish browser login.
8. Use **Test Connection**.
9. Save the connection.

## Endpoint and region

AWS S3 usually works best with an empty endpoint and the correct region. Use a region-specific endpoint only when your setup requires it.

| Region | Endpoint |
| --- | --- |
| `us-east-1` | `https://s3.us-east-1.amazonaws.com` |
| `us-west-2` | `https://s3.us-west-2.amazonaws.com` |
| Custom AWS-compatible endpoint | Use the provider endpoint instead of AWS S3 |

## Common issues and fixes

### Endpoint and region mismatch

If the endpoint does not match the bucket region, AWS can return 301 PermanentRedirect errors. Fix by using the bucket's region-specific endpoint, especially for buckets outside us-east-1.

### Path-style URL deprecation

Path-style URLs are planned for discontinuation. Fix by switching to virtual-hosted-style URLs for new integrations.

### Buckets do not load

If the credentials can access a bucket but cannot list all buckets, disable bucket listing and add bucket names manually.

### SSO profile is expired

Use **Login with SSO** from the connection form, then test the connection again.

### Access denied on preview or download

Preview, open, download, and share-link creation need object read permission. Add `s3:GetObject` for the target bucket path.