Amazon S3 integration is a feature that allows you to switch the storage destination of media such as images and videos uploaded from the microCMS management screen from the default storage of microCMS to an Amazon S3 bucket that you have prepared.
This enables you to apply security settings based on your company's policies, making it safe to use even for projects with high security requirements.

Pre-Usage Confirmation Items

To use the Amazon S3 integration feature, the following conditions must be met. All of these are important, so please make sure to check them.

• The only public cloud storage that can be integrated is Amazon S3 only.
• Enabling this feature will change the image delivery specifications, and the Image API will no longer be available. If you need image optimization (such as resizing or format conversion) via URL parameters, please use external services like imgix.
• The configuration of this feature cannot be completed solely through the management screen. In advance, you need to prepare resources related to your account in collaboration with us. For details on the configuration, please contact us first.
• Media uploaded to the external S3 bucket managed by you will be excluded from the regular storage backup that we perform regularly.

Feature Details

Typically, media (including files) uploaded to the management screen is stored in the storage managed by microCMS. With the Amazon S3 integration feature, you can save directly to an S3 bucket that you have prepared in advance.
As a result, the URL assigned to the media after upload will follow the domain defined by you in advance.
This feature also applies to media other than images (such as PDFs).

Example URL Before Configuration

Image

https://images.microcms-assets.io/assets/xxxx/yyyy/image.png

File

https://files.microcms-assets.io/assets/xxxx/yyyy/sample.pdf

Example URL After Configuration

Image

https://{bucket-name}.s3.{region-name}.amazonaws.com/media/image.png

File

https://{bucket-name}.s3.{region-name}.amazonaws.com/media/sample.pdf

※The bucket name and region name set by you will be included in the delivery URL.
※The above is an example when not using custom domain settings. For information on custom domain settings, please refer to "Setting in the microCMS Management Screen".

Upload Behavior

When this feature is enabled, the destination for media uploads will be the specified customer-managed S3 bucket.

The upload path will be target-bucket/{URL prefix}/{file name}. For file management purposes, the media will also have the following metadata attached.

• x-amz-meta-upload-source: "microcms"
• x-amz-meta-microcms-service: {Internal Service ID (e.g., SERVICE#xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)}
• x-amz-meta-microcms-version: {Timestamp format version (e.g., 20250812154922)}
• x-amz-meta-microcms-status: "public"

Media URL

Once this feature is enabled, media uploaded will be accessible via the following URL:
{Custom Domain}/{URL Prefix}/{File Name}

Possible Operations on Media

For media uploaded after this feature is enabled, the following operations are possible:

• Change of creator
• Tagging
• Setting alternative text

Additionally, the following operations will also be reflected in the files within the S3 bucket.

• Deletion of media
• Renaming of media (only when "URL fixation" is OFF)
• Re-uploading of media (only when "URL fixation" is OFF)

Configuration Method

Configuration Flow

Generally, the configuration is carried out in the following flow.

1. Prepare various resources needed for the configuration (S3 bucket, IAM role, etc.)
2. Access the management screen "Settings" > "External Integration" > "Amazon S3 Integration" and enter the necessary configuration items
3. Conduct a connection test
4. If there are no issues with the connection test, apply the configuration

Preparation

Please prepare the AWS-related resources listed below.

1. S3 Bucket (Required)

Please prepare one S3 bucket to store media.
Additionally, set a bucket policy that grants permissions for operations to the created bucket.

Example of Bucket Policy

If not using CloudFront with S3

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "<optional>",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::<bucket-name>/<directory-name>/*"
        }
    ]
}

If using CloudFront with S3

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "<optional>",
            "Effect": "Allow",
            "Principal": {
                "Service": "cloudfront.amazonaws.com"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::<bucket-name>/<directory-name>/*",
            "Condition": {
                "ArnLike": {
                    "AWS:SourceArn": "arn:aws:cloudfront::<account-id (12-digit number)>:distribution/<CloudFront distribution ID>"
                }
            }
        }
    ]
}

Notes

• Please select "General" for the "Bucket Type".
• Please select "Disable ACL" for the "Object Owner".

2. IAM Policy (Required)

Please prepare one IAM policy that grants permissions for various operations on the S3 bucket.

Example of IAM Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "<optional>",
            "Effect": "Allow",
            "Action": [
                "s3:GetBucketLocation",
                "s3:ListBucket"
            ],
            "Resource": "arn:aws:s3:::<bucket-name>"
        },
        {
            "Sid": "<optional>",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::<bucket-name>/<directory-name>/*"
        }
    ]
}

3. IAM Role (Required)

Please prepare one IAM role to be assigned when creating, modifying, or deleting S3 objects (media) from microCMS.
Attach the IAM policy created above to the IAM role you created.

Notes

• Please select "AWS Account" for the "Trusted Entity Type".
• Please select "Another AWS Account" for the "AWS Account". Details regarding the "Account ID" will be provided to you individually during the setup process.
• Optionally, check "Require External ID" and set any external ID.

4. CloudFront Distribution (Optional)

If you are using CloudFront to deliver objects in the S3 bucket, please prepare one CloudFront distribution.

Notes

• After creating the distribution, it may take time to deploy, so please ensure it is complete before configuring on the microCMS side.

Settings in the microCMS Management Screen

Please enter the configuration values shown below.

Restrictions / Notes

Notes on S3 Configuration and Data Management

The configuration of the linked S3 and the management and operation of the data within the bucket are the customer's responsibility.
Changes to data or settings made without using the microCMS management screen or API are not covered by support, so please be aware of this in advance.

Precautions When Integrating S3 with CloudFront and Other CDNs

When integrating S3 with CloudFront and other CDNs and utilizing caching, there may be cases where cached data remains even after deleting media in the microCMS management screen.

As a countermeasure, please consider the following methods:

1. Use media Webhooks to detect media deletion and explicitly remove the cache
2. Set a short TTL for the cache

In the case of the first option, depending on the use case, images may be cached with parameters appended to the URL. Therefore, when deleting the cache, please specify a wildcard at the end of the path.

Handling When Media Already Exists

If media already exists, media will be saved to the customer-managed external S3 bucket after this feature is enabled.

Additionally, if there is media uploaded to the customer-managed external S3 bucket, changes to the S3 integration settings and deletion of settings cannot be performed.

Support for WRITE API

Content API

Supports media registration via URL specification in POST / PUT / PATCH requests.

Management API

Does not support media POST and DELETE requests.

Handling in Multiple Environments

When creating multiple environments, the settings for this feature are also copied as initial settings.
Additionally, unlike the basic behavior during uploads, the upload destination path will be target-bucket/{URL prefix}/{unique value based on the service ID of the multiple environment}/{file name}.

The other specifications are as follows:

• When creating an environment, media will be copied to the directory mentioned above.
• When deleting an environment, all media in the directory mentioned above will be deleted.
• The S3 integration settings for the production environment and the S3 integration settings for multiple environments (development and staging) do not affect each other even if changes are made in one of the environments.

Other Considerations

• The media storage location is an external S3 bucket managed by the customer, so the costs for media data transfer and storage will be borne by the customer (however, there are no data transfer costs for microCMS).
• In the "Data Transfer Volume" feature, reading media stored in the external S3 bucket managed by the customer will not be reflected in the graphs for "Data Transfer Volume" and "Content Retrieval Count".