CORS (Cross-Origin Resource Sharing) Guide
Complete CORS reference: preflight requests, Access-Control headers, credentials, wildcard policies, and common pitfalls.
A guide to Cross-Origin Resource Sharing: the Access-Control response and request headers, what makes a request 'simple', and the common mistakes, such as combining a wildcard origin with credentials or forgetting to answer preflight requests.
Use it when
- You are debugging a browser CORS error.
- You are configuring an API for browser clients on another origin.
Watch out for
- CORS is enforced by browsers, not servers; non-browser clients are not subject to it.
- A permissive configuration can expose authenticated APIs to any site; allow only the origins you need.
The data
Headers
9 rows
| Header | Direction | Description | Example | Notes |
|---|---|---|---|---|
| Access-Control-Allow-Origin | Response | Specifies which origins can access the resource | Access-Control-Allow-Origin: https://example.com OR * (wildcard) | Cannot use * with credentials; must echo specific origin for credentialed requests |
| Access-Control-Allow-Methods | Response (preflight) | Allowed HTTP methods for the resource | Access-Control-Allow-Methods: GET, POST, DELETE | Returned in response to OPTIONS preflight; list only what's actually supported |
| Access-Control-Allow-Headers | Response (preflight) | Allowed custom headers in requests | Access-Control-Allow-Headers: Content-Type, Authorization, X-Custom-Header | Must include all non-simple headers the client needs to send |
| Access-Control-Expose-Headers | Response | Headers the browser is allowed to expose to client-side code | Access-Control-Expose-Headers: X-Total-Count, X-Page-Count | By default, only Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, Pragma are exposed |
| Access-Control-Allow-Credentials | Response | Whether cookies/auth are included in cross-origin requests | Access-Control-Allow-Credentials: true | Requires Access-Control-Allow-Origin to be a specific origin (not *) |
| Access-Control-Max-Age | Response (preflight) | How long (seconds) preflight result can be cached | Access-Control-Max-Age: 86400 | Reduces preflight overhead; browsers cap this (Chrome: 2h, Firefox: 24h) |
| Origin | Request | Client sends the origin making the request | Origin: https://example.com | Sent with all CORS requests; server uses this to decide whether to allow |
| Access-Control-Request-Method | Request (preflight) | Method that will be used in the actual request | Access-Control-Request-Method: DELETE | Sent in OPTIONS preflight to ask server if method is allowed |
| Access-Control-Request-Headers | Request (preflight) | Headers that will be used in the actual request | Access-Control-Request-Headers: Content-Type, Authorization | Sent in OPTIONS preflight to ask server if headers are allowed |
Simple requests
- Description
- Requests that don't trigger preflight (OPTIONS)
- Conditions
- Method is GET, HEAD, or POST only
- Headers are only: Accept, Accept-Language, Content-Language, Content-Type (with simple values)
- Content-Type is application/x-www-form-urlencoded, multipart/form-data, or text/plain
- No ReadableStream in request body
- Notes
- POST with application/json triggers preflight! Use application/x-www-form-urlencoded for simple POST.
Common mistakes
5 rows
| Mistake | Fix |
|---|---|
| Using * with credentials | Echo the specific Origin header value instead of * |
| Forgetting to handle OPTIONS method | Add OPTIONS handler that returns CORS headers for preflight |
| Not caching preflight responses | Add Access-Control-Max-Age to preflight responses |
| Exposing custom headers without Access-Control-Expose-Headers | Add Access-Control-Expose-Headers for any custom response headers client needs |
| Returning CORS headers on all responses including errors | Ensure CORS headers are present on 4xx/5xx responses too |
Fields
The shape of this dataset, read from the data itself: every column, its type and a real value. Agents can use this to plan a query without fetching the whole document.
| Section | Field | Type | Example |
|---|---|---|---|
| headers | header | string | Access-Control-Allow-Origin |
| headers | direction | string | Response |
| headers | description | string | Specifies which origins can access the resource |
| headers | example | string | Access-Control-Allow-Origin: https://example.co… |
| headers | notes | string | Cannot use * with credentials; must echo specif… |
| simple_requests | * | object | {description,conditions,notes} |
| common_mistakes | mistake | string | Using * with credentials |
| common_mistakes | fix | string | Echo the specific Origin header value instead o… |
Fetch the same bytes
The static files contain the same reference rows as the API, with no API rate limit. Live metadata, such as view counts, may differ. Use the API for content negotiation; use the static files for a cacheable snapshot.
curl "https://yjtoon.com/api/dataset/http-cors-guide?format=toon"
const res = await fetch( "https://yjtoon.com/static-data/dataset/http-cors-guide.toon" ); const toon = await res.text();
Rate limit: 120 requests per minute per IP, no key and no signup. API reference →