CORS
CORS (cross-origin resource sharing) is a browser safety rule: a web page on https://app.example.com may only call another address — such as your bucket — if that address says the page’s site is allowed. A CORS rule on your bucket is that permission. You need one when JavaScript in a browser talks to the bucket directly, for example to upload a file with a presigned URL or to fetch() a JSON file.
When you need a CORS rule
How it works
- Before some requests, the browser sends a preflight request (
OPTIONS) asking: may this origin use this method and these headers? - IBEE compares the request with the bucket’s rules. The first rule that matches the origin, method and headers allows it.
- If no rule matches, the browser blocks the request and shows a CORS error in the console.
An origin is the scheme, host and port of the page, such as https://app.example.com — no path and no trailing slash.
Before you begin
- A bucket. See Create a bucket.
- Write access to the bucket’s settings, or a platform API token with
object-storage.write. - The exact origin of your site, for example
https://app.example.comand, for local testing,http://localhost:3000.
Add a rule in the portal
Open CORS settings
Open the bucket, click Settings, then CORS. A bucket without rules shows No CORS rules.
Enter the allowed origins
Under Allowed Origins, type an origin, such as https://app.example.com. Click Add Origin to add more. Accepted forms:
Always include http:// or https://. A value such as *.example.com without a scheme is refused.
Choose the methods
Under Allowed Methods, tick what the page does: GET (ticked by default) to read, PUT to upload, HEAD to check a file, DELETE to delete, POST if your code sends it.
CORS rules are cached. Changes can take up to 5 minutes to apply — wait before you test.
Add a rule with the API
PUT replaces all the bucket’s rules with the list you send. This rule allows browser uploads from one site:
max_age_seconds is how long a browser may reuse a preflight answer. GET on the same path returns the rules (currently with the keys in S3 casing, such as AllowedOrigins); DELETE removes them all and needs object-storage.delete. The S3 call PutBucketCors returns 501 on the S3 endpoint.
Verify
After 5 minutes, send a preflight from your terminal. Replace the origin and object path with yours:
A matching rule returns Access-Control-Allow-Origin: https://app.example.com in the response headers. In the browser, the console shows no CORS error.
Edit or delete a rule
Each rule in the CORS Policy list has Edit and Delete. Edit opens the Edit CORS Rule dialog; click Save Rule. Delete asks you to confirm in the Delete CORS rule dialog.
Limits
Security tips
- Allow only your own sites. Avoid
*on a bucket that accepts uploads. - Allow only the methods you use. A read-only site needs only
GET(andHEAD). - CORS doesn’t replace access control: a private bucket still needs a presigned URL or credential for each request.
Troubleshooting
Related pages
- Presigned URLs: browser uploads with a link
- Bucket Policies
- Static Site Hosting
- Buckets
