Adding an Amazon S3 Source

An Amazon S3 Source connects to an existing Amazon S3 bucket. imgix connects using the credentials you supply, so assets don't have to be public.

Setting Up Your S3 Source

Note: When retrieving S3 objects from the us-east-1 region, imgix uses the s3-external-1.amazonaws.com hostname to retrieve assets whenever possible to ensure read-after-write consistency, and will fall back to the default hostname of s3.amazonaws.com if necessary.

Go to the Sources page in the imgix dashboard and click the New Source button.
Select Amazon S3 from the How do you store your media? radio options.
Fill in the details for your Amazon S3 Source. Note: We strongly recommend creating an Amazon IAM account specifically for imgix to access your S3 bucket with. Keep in mind that imgix only requires Read and List permissions to begin serving your assets. For more information on permissions, how to generate your Access Key and Secret Access Keys, or where to find your Bucket Name see the Amazon S3 Guide and Security documentation.
- Access Key ID: The access key of the deployment credentials you want imgix to connect with.
- Secret Access Key: The secret key of the deployment credentials you want imgix to connect with.
- Bucket Name: The name of the bucket containing the assets you want imgix to connect to.
- Path Prefix (optional): The folder prefix you want to resolve to (if it exists). The prefix is prepended to the asset path before resolving the asset in S3. By default the asset path is /.
Name the Subdomain you'd like to use as the base URL for your assets.

Note: The subdomain name you choose is unique to your Source and can't be re-used. If you're setting up a Source with a lot of customization (particularly a Custom Domain), choose the name you plan to use going forward.
- If you are editing an existing Source and the Video API is enabled, the imgix Video Subdomain field will be visible. This field automatically inherits the value from your imgix Image Subdomain and cannot be modified without changing the Image Subdomain.
Click the Deploy Source button on Step #3 to queue your Source for deployment.

Amazon S3 Guide and Security

We strongly recommend creating an Amazon IAM user specifically for imgix to access your S3 bucket with. All Amazon credentials are stored using industry standard cryptographic best practices.

IAM users help businesses maintain security by only granting specific individuals or, in our case, a specific application access to their S3 buckets. imgix only requires read permissions to connect to your bucket and begin serving your media.

Advanced Policy Template

imgix only needs a few read-only permissions to properly fetch assets. To add an additional layer of security, use a limited-permissions IAM user that is only used for imgix and only for the bucket containing your assets.

The specific S3 permissions imgix requires are:

ListBucket
GetBucketLocation
GetObject

Advanced Policy Example

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket/*",
        "arn:aws:s3:::your-bucket"
      ]
    }
  ]
}

Note: If you decide to manually build your policy, please double-check it with the Amazon IAM Policy Simulator.

Advanced Settings

See the Advanced Source Settings for information about setting up custom domains, defaults, and cache TTL options.

Uploading

To upload images and videos directly to your cloud-storage-backed Amazon S3 Source, you will have to create a separate set of upload_credentials. To upload to your Source directly through Asset Manager, you will also have to update your bucket’s CORS configuration. Uploading should only be set up post-Source-deployment.

imgix’s rendering service does not need Write permissions to fetch assets; therefore, we highly recommend that you do not use the same credentials for your upload_credentials and your deployment_credentials.

Next: Serving Assets