Amazon S3 bucket origin

You can add your existing Amazon S3 bucket as an origin in This allows you to use real-time image optimization and resizing features on all existing images stored in the bucket.

How to add an Amazon S3 bucket origin?

  1. Go to the Integration section of your dashboard and click on the "Add origin" button.

  2. Give your origin a name, it will appear in the list of origins you have added. For example - Product images bucket.

  3. Fill out the S3 bucket name. For example, product-images

  4. Specify the S3 bucket folder in which your images are present. If you have to access files at the root (i.e., present directly in the bucket and not inside a folder), enter /.

  5. Fill out S3 access and secret keys. These keys should provide read-only access to as explained below.

  6. Leave the advanced options as it is, for now.

  7. Click on Submit button.

The newly added origin will start appearing under Image origin list in the Integration section. Similarly, you can add multiple S3 bucket origins in the same account.

Read-only permission required needs read-only access to your S3 bucket. You can provide this by using the AWS Identity and Access Management (AIM) policy for your S3 bucket. Ideally, you should create a separate user for this purpose and assign the AIM policy for that particular user and the required buckets only.

Note that you need to provide permission for the operation s3::GetObject on the objects in your bucket. The minimal permission policy should look like:

"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"Resource": [

Access the image through URL-endpoint

Let's assume the original image in your S3 bucket with the name my-bucket is kept at the path path/to/my/image.jpg. Assuming you have added this bucket with folder as / , then it can be accessed through your default URL-endpoint now -

We just add the new URL endpoint, i.e., the path of the image in the bucket.

🧙♂Using custom domain You can also use a custom domain like, but in this documentation, we will stick with URL format. Learn more about how to use a custom domain.

Handling special characters in file name

While fetching images from your S3 bucket with special characters in the name, you will get a 404 NOT FOUND response. For example, let’s assume that there is a key image%2Bexample.jpg in your S3 bucket, and the request is made using image+example.jpg in the URL. In this case, tries to fetch image+example.jpg object from the S3 bucket resulting in a 404 error as this object does not exist.

While adding S3 bucket as a source in your account, you are now provided with an option to encode the keys while fetching the object from your S3 bucket. By default, this option is disabled. When enabled, the requests made while fetching images will be made using encoded keys.

Note: At present, this feature can only be enabled upon request, please email support at

Advanced options for S3 type origin

Include canonical response header

When enabled, the image response contains a Link header with the appropriate URL and rel=canonical. You will have to specify the base URL for the canonical header.

For example, if you set as the base URL for canonical header, then the image response for URL will have a Link header like this:

Link: <>; rel="canonical"