Amazon S3 provider#

The @strapi/provider-upload-aws-s3 package lets you store Media Library assets on Amazon S3 or any S3-compatible service (Cloudflare R2, Scaleway, MinIO, etc.). This page covers provider configuration, required AWS setup (IAM, CORS, middleware), and extended options such as encryption, checksums, and signed URLs for private buckets.

The Media Library feature is powered by a back-end server package called Upload which leverages the use of providers.

Strapi maintains 3 providers for the Media Library. The present page is about the Amazon S3 provider installation and configuration. For other providers, please refer to the list in the Media Library page.

Installation#

To install the official Strapi-maintained AWS S3 provider, run the following command in a terminal:

yarn add @strapi/provider-upload-aws-s3

npm install @strapi/provider-upload-aws-s3 --save

Configuration#

Providers configuration is defined in the /config/plugins file. If this file does not exist, create it first. When using a different provider per environment, specify the correct configuration in /config/env/${yourEnvironment}/plugins.js|ts (see environments).

The provider configuration accepts the following entries:

provider to define the provider name (i.e., amazon-s3)
providerOptions to define options that are passed down during the construction of the provider (see for the full list of options; some examples are given in the dedicated extended provider options section)
actionOptions to define options that are passed directly to the parameters to each method respectively. The official AWS documentation lists available options for and .

Basic example#

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        baseUrl: env('CDN_URL'),
        rootPath: env('CDN_ROOT_PATH'),
        s3Options: {
          credentials: {
            accessKeyId: env('AWS_ACCESS_KEY_ID'),
            secretAccessKey: env('AWS_ACCESS_SECRET'),
          },
          region: env('AWS_REGION'),
          params: {
            ACL: env('AWS_ACL', 'public-read'),
            signedUrlExpires: env('AWS_SIGNED_URL_EXPIRES', 15 * 60),
            Bucket: env('AWS_BUCKET'),
          },
        },
      },
      actionOptions: {
        upload: {},
        uploadStream: {},
        delete: {},
      },
    },
  },
  // ...
});

export default ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        baseUrl: env('CDN_URL'),
        rootPath: env('CDN_ROOT_PATH'),
        s3Options: {
          credentials: {
            accessKeyId: env('AWS_ACCESS_KEY_ID'),
            secretAccessKey: env('AWS_ACCESS_SECRET'),
          },
          region: env('AWS_REGION'),
          params: {
            ACL: env('AWS_ACL', 'public-read'),
            signedUrlExpires: env('AWS_SIGNED_URL_EXPIRES', 15 * 60),
            Bucket: env('AWS_BUCKET'),
          },
        },
      },
      actionOptions: {
        upload: {},
        uploadStream: {},
        delete: {},
      },
    },
  },
  // ...
});

If you use the bucket as a CDN and deliver the content on a custom domain, you can use the baseUrl and rootPath properties. Use environment configurations to define how your asset URLs will be saved inside Strapi.

:::info AWS SDK V3 URL format
The provider uses AWS SDK V3, which defaults to for S3 URLs. To use path-style URLs instead, set baseUrl explicitly:

baseUrl: `https://s3.${process.env.AWS_REGION}.amazonaws.com/${process.env.AWS_BUCKET}`,

:::

:::caution Deprecated root-level credential format
Older Strapi guides and blog posts show accessKeyId and secretAccessKey placed directly in s3Options. This root-level format still works but triggers a deprecation warning. Pass credentials inside a credentials object instead (as shown in the examples above).
:::

:::info AWS credential provider functions
Instead of a static credentials object, you can pass an AWS credential provider function (e.g., from @aws-sdk/credential-providers) to s3Options.credentials. This allows credentials to be resolved and refreshed at runtime without restarting the process, which is useful when credentials change during application lifetime (e.g., temporary credentials, credential rotation):

import { fromNodeProviderChain } from '@aws-sdk/credential-providers';

export default ({ env }) => ({
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        s3Options: {
          credentials: fromNodeProviderChain(), // AWS SDK resolves credentials dynamically
          region: env('AWS_REGION'),
          params: {
            Bucket: env('AWS_BUCKET'),
          },
        },
      },
    },
  },
});

The provider function must return a promise that resolves to credentials with accessKeyId and secretAccessKey properties.
:::

To ensure the provider works correctly, you also need to configure IAM permissions, bucket CORS, and the Strapi security middleware (see Required setup).

Private bucket and signed URLs#

If your bucket is configured to be private, set the ACL option to private in the params object. This ensures file URLs are signed.

You can define the expiration time of the signed URL by setting the signedUrlExpires option in the params object. The default value is 15 minutes.

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        s3Options: {
          credentials: {
            accessKeyId: env('AWS_ACCESS_KEY_ID'),
            secretAccessKey: env('AWS_ACCESS_SECRET'),
          },
          region: env('AWS_REGION'),
          params: {
            ACL: 'private', // <== set ACL to private
            signedUrlExpires: env('AWS_SIGNED_URL_EXPIRES', 15 * 60),
            Bucket: env('AWS_BUCKET'),
          },
        },
      },
      actionOptions: {
        upload: {},
        uploadStream: {},
        delete: {},
      },
    },
  },
  // ...
});

Required setup#

The following are the minimum configuration actions to take into account for your AWS S3 setup to work with the Media Library.

IAM policy actions#

The following are the minimum amount of permissions needed for the AWS S3 provider to work:

"Action": [
  "s3:PutObject",
  "s3:GetObject",
  "s3:ListBucket",
  "s3:DeleteObject",
  "s3:PutObjectAcl"
],

Bucket CORS configuration#

To display thumbnails for GIFs and videos uploaded to S3, edit your bucket's CORS configuration so that thumbnails are properly shown in Strapi. To do so:

Open your bucket in the AWS console.
Navigate to the Permissions tab.
Locate the Cross-origin resource sharing (CORS) field.
Add the following CORS policy (or adapt it to your needs):

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["YOUR STRAPI URL"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3000
  }
]

Security middleware configuration#

The default Strapi security middleware settings block S3 thumbnail previews in the Media Library. Modify the contentSecurityPolicy settings to allow loading media from your S3 bucket. Replace the strapi::security string with the following object (see middleware configuration for details):

module.exports = [
  // ...
  {
    name: 'strapi::security',
    config: {
      // highlight-start
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          'connect-src': ["'self'", 'https:'],
          'img-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'yourBucketName.s3.yourRegion.amazonaws.com',
          ],
          'media-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'yourBucketName.s3.yourRegion.amazonaws.com',
          ],
          upgradeInsecureRequests: null,
        },
      },
      // highlight-end
    },
  },
  // ...
];

If your bucket name contains dots and forcePathStyle is false, S3 uses directory-style URLs, such as in:

s3.yourRegion.amazonaws.com/your.bucket.name/image.jpg

In this case, use s3.yourRegion.amazonaws.com (without the bucket name) for the img-src and media-src directives.

S3-compatible services#

The AWS S3 provider works with S3-compatible services by using the endpoint option. When an S3-compatible provider returns a valid URL in its upload response, the provider trusts that URL as-is, preserving the correct format (virtual-hosted or path-style) for the provider. For providers that return malformed URLs in multipart upload responses (e.g., IONOS, some MinIO configurations), the provider falls back to constructing the URL from the endpoint configuration.

Some providers require forcePathStyle: true in the s3Options. This option is needed when the provider does not support virtual-hosted-style URLs (e.g., bucket.endpoint.com), and instead uses path-style URLs (e.g., endpoint.com/bucket).

The following table shows compatibility settings for each provider:

Provider	`forcePathStyle`	`ACL`	Notes
IONOS	`true`	Supported	Malformed multipart `Location` auto-fixed via endpoint fallback
MinIO	`true`	Supported	Some configurations may return malformed `Location`; auto-fixed via endpoint fallback
Contabo	`true`	Supported	-
Hetzner	`true`	Supported	-
DigitalOcean Spaces	Not needed	Supported	Returns correct virtual-hosted URLs
Wasabi	Not needed	Supported	-
Scaleway	Not needed	Supported	Returns correct virtual-hosted URLs
Vultr	Not needed	Supported	-
Backblaze B2	Not needed	Supported	Returns correct virtual-hosted URLs
Cloudflare R2	Not needed	Not supported	Omit `ACL` from parameters

Scaleway#

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        // highlight-start
        s3Options: {
          credentials: {
            accessKeyId: env('SCALEWAY_ACCESS_KEY_ID'),
            secretAccessKey: env('SCALEWAY_ACCESS_SECRET'),
          },
          region: env('SCALEWAY_REGION'), // e.g "fr-par"
          endpoint: env('SCALEWAY_ENDPOINT'), // e.g. "https://s3.fr-par.scw.cloud"
          params: {
            Bucket: env('SCALEWAY_BUCKET'),
          },
        },
        // highlight-end
      },
    },
  },
  // ...
});

IONOS / MinIO / Contabo#

These providers require forcePathStyle: true because they use path-style URLs instead of virtual-hosted-style URLs.

module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        // highlight-start
        s3Options: {
          credentials: {
            accessKeyId: env('S3_ACCESS_KEY_ID'),
            secretAccessKey: env('S3_ACCESS_SECRET'),
          },
          region: env('S3_REGION'),
          endpoint: env('S3_ENDPOINT'),
          forcePathStyle: true, // Required for these providers
          params: {
            Bucket: env('S3_BUCKET'),
          },
        },
        // highlight-end
      },
    },
  },
});

Cloudflare R2#

Cloudflare R2 does not support ACLs.

module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        // highlight-start
        s3Options: {
          credentials: {
            accessKeyId: env('R2_ACCESS_KEY_ID'),
            secretAccessKey: env('R2_ACCESS_SECRET'),
          },
          region: 'auto',
          endpoint: env('R2_ENDPOINT'), // e.g. "https://<account-id>.r2.cloudflarestorage.com"
          params: {
            Bucket: env('R2_BUCKET'),
            // Do NOT set ACL - R2 does not support ACLs
          },
        },
        // highlight-end
      },
    },
  },
});

Extended provider options#

The providerConfig option inside providerOptions provides additional features for data integrity, security, and cost optimization.

Enable [server-side encryption](#server-side-encryption) for data at rest Enable [checksum validation](#checksum-validation) for upload integrity Enable [conditional writes](#conditional-writes-prevent-overwrites) to prevent race conditions Use `ACL: 'private'` with [signed URLs](#private-bucket-and-signed-urls) for sensitive content Enable for recovery from accidental deletions

Checksum validation#

Enable automatic checksum calculation to ensure data integrity during uploads. The SDK calculates a checksum on the client side, and S3 validates the checksum server-side.

providerOptions: {
  s3Options: { /* ... */ },
  providerConfig: {
    checksumAlgorithm: 'CRC64NVME', // Options: 'CRC32', 'CRC32C', 'SHA1', 'SHA256', 'CRC64NVME'
  },
},

CRC64NVME is recommended for best performance on modern hardware.

Conditional writes (prevent overwrites)#

Prevent accidental file overwrites due to race conditions by enabling conditional writes. When enabled, uploads will fail if an object with the same key already exists.

providerConfig: {
  preventOverwrite: true,
},

Storage class (AWS S3 only)#

Optimize storage costs by specifying a storage class for uploaded objects. Use lower-cost classes for infrequently accessed data.

providerConfig: {
  storageClass: 'INTELLIGENT_TIERING', // Auto-optimizes costs
},

Available storage classes:

STANDARD - Frequently accessed data (default)
INTELLIGENT_TIERING - Automatic cost optimization
STANDARD_IA - Infrequently accessed data
ONEZONE_IA - Infrequently accessed, single AZ
GLACIER - Archive storage
DEEP_ARCHIVE - Long-term archive
GLACIER_IR - Glacier Instant Retrieval

Server-side encryption#

Configure server-side encryption for compliance requirements (GDPR, HIPAA, etc.).

providerConfig: {
  encryption: {
    type: 'AES256', // S3-managed encryption
  },
},

For KMS-managed encryption (AWS S3 only):

providerConfig: {
  encryption: {
    type: 'aws:kms',
    kmsKeyId: env('AWS_KMS_KEY_ID'),
  },
},

Available encryption types:

AES256 - S3-managed keys (SSE-S3) — supported by most S3-compatible providers
aws:kms - AWS KMS-managed keys (SSE-KMS) — AWS S3 only
aws:kms:dsse - Dual-layer SSE with KMS — AWS S3 only

Object tagging#

Apply tags to uploaded objects for cost allocation, lifecycle policies, and organization.

providerConfig: {
  tags: {
    project: 'website',
    environment: 'production',
    team: 'backend',
  },
},

Multipart upload configuration#

Configure multipart upload behavior for large files.

providerConfig: {
  multipart: {
    partSize: 10 * 1024 * 1024, // 10MB per part
    queueSize: 4, // Number of parallel uploads
    leavePartsOnError: false, // Clean up on failure
  },
},

Complete configuration example#

module.exports = ({ env }) => ({
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        baseUrl: env('CDN_URL'),
        rootPath: env('CDN_ROOT_PATH'),
        s3Options: {
          credentials: {
            accessKeyId: env('AWS_ACCESS_KEY_ID'),
            secretAccessKey: env('AWS_ACCESS_SECRET'),
          },
          region: env('AWS_REGION'),
          params: {
            ACL: 'private',
            signedUrlExpires: 15 * 60,
            Bucket: env('AWS_BUCKET'),
          },
        },
        providerConfig: {
          checksumAlgorithm: 'CRC64NVME',
          preventOverwrite: true,
          storageClass: 'INTELLIGENT_TIERING',
          encryption: {
            type: 'aws:kms',
            kmsKeyId: env('AWS_KMS_KEY_ID'),
          },
          tags: {
            application: 'strapi',
            environment: env('NODE_ENV'),
          },
          multipart: {
            partSize: 10 * 1024 * 1024,
            queueSize: 4,
          },
        },
      },
    },
  },
});

Custom provider override (private S3 provider) {#private-aws-s3-provider}#

For most private bucket use cases, setting ACL: 'private' in the provider configuration (see Private bucket and signed URLs) is sufficient. The provider handles URL signing automatically.

However, if you need full control over the signing logic, you can override the provider locally. This could be used to set custom expiration times per file, conditional access rules, or integration with an external authorization service.

To create a custom aws-s3 provider override:

Create a /providers/aws-s3 folder in your application (see local providers for more information).
Implement the isPrivate() method in the aws-s3 provider to return true.
Implement the getSignedUrl(file) method in the aws-s3 provider to generate a signed URL for the given file.

module.exports = {
  init: (config) => {
    const s3 = new AWS.S3(config);

    return {
      async upload(file) {
        // code to upload file to S3
      },

      async delete(file) {
        // code to delete file from S3
      },

      async isPrivate() {
        return true;
      },

      async getSignedUrl(file) {
        const params = {
          Bucket: config.params.Bucket,
          Key: file.path,
          Expires: 60, // URL expiration time in seconds
        };

        const signedUrl = await s3.getSignedUrlPromise("getObject", params);
        return { url: signedUrl };
      },
    };
  },
};

export = {
  init: (config) => {
    const s3 = new AWS.S3(config);

    return {
      async upload(file) {
        // code to upload file to S3
      },

      async delete(file) {
        // code to delete file from S3
      },

      async isPrivate() {
        return true;
      },

      async getSignedUrl(file) {
        const params = {
          Bucket: config.params.Bucket,
          Key: file.path,
          Expires: 60, // URL expiration time in seconds
        };

        const signedUrl = await s3.getSignedUrlPromise("getObject", params);
        return { url: signedUrl };
      },
    };
  },
};