2025.5.1
Home ▸ Integrations ▸

AWS S3

The AWS S3 integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to use AWS S3 bucket with Home Assistant Backups.

Prerequisites

Important

This integration is specifically designed to work only with Amazon AWS S3 and not with third-party storage providers that claim S3 API compatibility. Third-party providers like Wasabi, DigitalOcean Spaces, Backblaze B2, Infomaniak, and others are not supported.

This integration requires an existing S3 bucket and an IAM user that has access to that bucket. For security reasons, it is strongly recommended to scope the IAM policy as narrowly as possible to only the required operations and resources.

Create a new S3 bucket
  1. Log in to the AWS Management Console.
  2. Navigate to S3 from the Services menu.
  3. Click Create bucket.
  4. Choose a unique bucket name (e.g., home-assistant-backups-123456).
  5. Select your preferred AWS region (e.g., eu-central-1).
  6. Adjust the settings:
    • ✅ Block all public access (enabled by default, recommended)
    • ⚠️ Enable Bucket Versioning (optional). This lets you recover backups after Home Assistant deletes them, but it can increase storage costs. Disable this to allow permanent deletion based on retention settings.
  7. Click Create bucket.

Make a note of the bucket name — you’ll need it later.

Create an IAM user

To create a new IAM user that can access the S3 bucket:

  1. Go to IAM > Users in the AWS Management Console.
  2. Click Add users.
  3. Use a name like home-assistant-backup.
  4. Check Access key - Programmatic access only.
  5. Click Next: Permissions.

Now, let’s create and attach a custom IAM policy to give the user the necessary permissions to the bucket:

  1. Click Create policy, go to the JSON tab, and paste the following (replace YOUR_BUCKET_NAME):

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowS3BackupOperations",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

  2. Name the policy (e.g., HomeAssistantS3Policy) and create it.

  3. Return to the user creation wizard and attach the new policy.

  4. Complete the user setup.

  5. Save the Access Key ID and Secret Access Key — you’ll need these when setting up the AWS S3 integration in Home Assistant.

Note

  • Avoid using credentials for your AWS root account or IAM users that have more permissions than is necessary.

  • By limiting credentials to a specific bucket, you reduce risk and help keep your AWS account secure.

Configuration

To add the AWS S3 service to your Home Assistant instance, use this My button:

Manual configuration steps

If the above My button doesn’t work, you can also perform the following steps manually:

Access Key ID

The access key ID for your AWS S3 account.

Secret Access Key

The secret access key for your AWS S3 account.

Bucket Name

S3 bucket name to store the backups. Bucket must already exist and be writable by the provided credentials.

Endpoint URL

Endpoint URL provided to Boto3 Session. Region-specific AWS S3 endpoints are available in their documentation. Defaults to https://s3.eu-central-1.amazonaws.com/.

Setting up the AWS S3 integration in Home Assistant

  1. In Home Assistant, go to Settings > Devices & Services.
  2. Click Add Integration and search for AWS S3.
  3. Enter the following details:
    • Access Key ID and Secret Access Key from the IAM user
    • Your bucket name
    • The region endpoint (e.g., https://s3.eu-central-1.amazonaws.com/)

The integration will test the connection and confirm access to your S3 bucket.

Known limitations

The AWS S3 integration has the following limitations:

No support for third-party S3 API compatible providers

This integration is designed to work only with the official Amazon AWS S3 service. Despite claims of S3 API compatibility, third-party storage providers like Wasabi, DigitalOcean Spaces, Backblaze B2, Infomaniak, OVH Cloud, and others have often proven to be incompatible. Even when they appear to work initially, they cannot guarantee ongoing compatibility with this AWS S3 integration in the future.

Removing the integration

This integration follows standard integration removal. No extra steps are required.

To remove an integration instance from Home Assistant

  1. Go to Settings > Devices & services and select the integration card.
  2. From the list of devices, select the integration instance you want to remove.
  3. Next to the entry, select the three-dot menu. Then, select Delete.