Skip to navigation

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

SituationCORS rule needed?
JavaScript on your site uploads to the bucket with a presigned PUT linkYes: allow your site, PUT, and the Content-Type header
JavaScript on your site fetch()es files from the bucketYes: allow your site and GET
A page shows bucket images with <img src> or links with <a href>No
Your server, CLI or SDK uses the bucketNo — CORS applies only to browsers

How it works

  1. Before some requests, the browser sends a preflight request (OPTIONS) asking: may this origin use this method and these headers?
  2. IBEE compares the request with the bucket’s rules. The first rule that matches the origin, method and headers allows it.
  3. 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.com and, for local testing, http://localhost:3000.

Add a rule in the portal

1

Open CORS settings

Open the bucket, click Settings, then CORS. A bucket without rules shows No CORS rules.

2

Add a rule

Click Add Rule on the CORS Policy card. The Add CORS Rule dialog opens.

3

Enter the allowed origins

Under Allowed Origins, type an origin, such as https://app.example.com. Click Add Origin to add more. Accepted forms:

FormExampleMatches
Exact originhttps://app.example.comOnly that origin
Subdomain wildcardhttps://*.example.comAny subdomain of example.com over HTTPS
Everything*Any website — avoid this for upload rules

Always include http:// or https://. A value such as *.example.com without a scheme is refused.

4

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.

5

Set the headers

Under Allowed Headers, list the headers the browser sends, separated by commas — for example Content-Type for uploads. The default * allows any header.

6

Save

Click Save Rule. The rule appears in the CORS Policy list.

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:

curl -X PUT "https://api.ibee.ai/v1/object-storage/buckets/my-bucket/cors?workspace_id=YOUR-WORKSPACE-ID" \
-H "Authorization: Bearer $IBEE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"rules": [{"allowed_origins": ["https://app.example.com"], "allowed_methods": ["GET", "PUT"], "allowed_headers": ["Content-Type"], "max_age_seconds": 3600}]}'

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:

curl -i -X OPTIONS "https://WORKSPACE-ID.blob.ibeestorage.com/my-bucket/uploads/test.png" \
-H "Origin: https://app.example.com" \
-H "Access-Control-Request-Method: PUT" \
-H "Access-Control-Request-Headers: content-type"

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

Value
Time for a change to applyUp to 5 minutes
Origin format*, or starting with http:// or https://
Subdomain wildcardhttps://*.example.com (scheme required)
MethodsGET, PUT, POST, DELETE, HEAD
Default headers in the portal*

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 (and HEAD).
  • CORS doesn’t replace access control: a private bucket still needs a presigned URL or credential for each request.

Troubleshooting

You seeWhat it meansWhat to do
Browser console: No ‘Access-Control-Allow-Origin’ header is presentNo rule matches the page’s originAdd the exact origin, with scheme and port, and wait 5 minutes.
The rule won’t save, with Invalid origin … must start with http:// or https://The origin has no scheme, for example *.example.comWrite https://*.example.com or the full origin.
Uploads fail but downloads workPUT isn’t allowed, or the Content-Type header isn’tTick PUT and allow Content-Type (or *).
It works from localhost but not production, or the reverseOnly one origin is listedAdd both origins.
The origin is listed but still blockedIt has a trailing slash or path, or http vs https differsUse the bare origin, such as https://app.example.com.
Changes have no effectThe cache hasn’t refreshedWait 5 minutes and reload with the cache cleared.
A 403 with no CORS errorThe request reached IBEE but was refused (expired link, wrong key)See Presigned URLs.