diff --git a/docs/api/04-standard-library/cloud/bucket.md b/docs/api/04-standard-library/cloud/bucket.md
index 64c36252f95..e983561fe8d 100644
--- a/docs/api/04-standard-library/cloud/bucket.md
+++ b/docs/api/04-standard-library/cloud/bucket.md
@@ -99,6 +99,41 @@ store.onDelete(inflight (key: str) => {
 });
 ```
 
+### Configuring CORS
+
+By default, buckets are configured with CORS for any origin. When a bucket is private (the default), CORS options only come into play when the bucket's objects are accessed through a signed URL.
+
+```js playground example
+bring cloud;
+
+let uploads = new cloud.Bucket(
+  // these are the default options:
+  public: false,
+  cors: true,
+  corsOptions: {
+    allowedMethods: [http.HttpMethod.GET, http.HttpMethod.POST, http.HttpMethod.PUT, http.HttpMethod.DELETE, http.HttpMethod.HEAD]
+    allowedOrigins: ["*"],
+    allowedHeaders: ["*"],
+    exposeHeaders: [],
+    maxAge: 0s
+  },
+)
+```
+
+The CORS configuration can be disabled by passing `cors: false` to the constructor. CORS rules can also be configured after the bucket is created by calling the `addCorsRule` method:
+
+```js playground example
+bring cloud;
+
+let bucket = new cloud.Bucket(
+  cors: false, // disable any default CORS rules
+);
+
+bucket.addCorsRule({
+  allowedOrigins: ["https://example.com"],
+});
+```
+
 ## Target-specific details
 
 ### Simulator (`sim`)
diff --git a/packages/@winglang/sdk/src/cloud/bucket.md b/packages/@winglang/sdk/src/cloud/bucket.md
index 1384616d717..e6895a1a654 100644
--- a/packages/@winglang/sdk/src/cloud/bucket.md
+++ b/packages/@winglang/sdk/src/cloud/bucket.md
@@ -99,6 +99,41 @@ store.onDelete(inflight (key: str) => {
 });
 ```
 
+### Configuring CORS
+
+By default, buckets are configured with CORS for any origin. When a bucket is private (the default), CORS options only come into play when the bucket's objects are accessed through a signed URL.
+
+```js playground example
+bring cloud;
+
+let uploads = new cloud.Bucket(
+  // these are the default options:
+  public: false,
+  cors: true,
+  corsOptions: {
+    allowedMethods: [http.HttpMethod.GET, http.HttpMethod.POST, http.HttpMethod.PUT, http.HttpMethod.DELETE, http.HttpMethod.HEAD]
+    allowedOrigins: ["*"],
+    allowedHeaders: ["*"],
+    exposeHeaders: [],
+    maxAge: 0s
+  },
+)
+```
+
+The CORS configuration can be disabled by passing `cors: false` to the constructor. CORS rules can also be configured after the bucket is created by calling the `addCorsRule` method:
+
+```js playground example
+bring cloud;
+
+let bucket = new cloud.Bucket(
+  cors: false, // disable any default CORS rules
+);
+
+bucket.addCorsRule({
+  allowedOrigins: ["https://example.com"],
+});
+```
+
 ## Target-specific details
 
 ### Simulator (`sim`)
diff --git a/tests/sdk_tests/bucket/cors.test.w b/tests/sdk_tests/bucket/cors.test.w
index a6265b88d00..69893fd776e 100644
--- a/tests/sdk_tests/bucket/cors.test.w
+++ b/tests/sdk_tests/bucket/cors.test.w
@@ -6,11 +6,13 @@ bring expect;
 
 let api = new cloud.Api();
 
-let bucket = new cloud.Bucket(public: true, cors: false);
-
-bucket.addCorsRule(
-  allowedMethods: [http.HttpMethod.GET],
-  allowedOrigins: [api.url]
+let bucket = new cloud.Bucket(
+  public: false,
+  cors: true,
+  corsOptions: {
+    allowedMethods: [http.HttpMethod.GET],
+    allowedOrigins: [api.url]
+  },
 );
 
 bucket.addObject("hello", "hello");