api: YAML JSON TOON Database
version: 1.0.0
format: toon
dataset:
  id: 2402
  slug: http-cors-guide
  title: CORS (Cross-Origin Resource Sharing) Guide
  description: "Complete CORS reference: preflight requests, Access-Control headers, credentials, wildcard policies, and common pitfalls."
  summary: "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_when[2]: You are debugging a browser CORS error.,You are configuring an API for browser clients on another origin.
  caveats[2]: "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.
  related[4]: http-request-headers,http-response-headers,common-vulnerabilities-owasp,browser-web-apis-reference
  entry_count: 14
  fields[8]{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…
  category: HTTP Status Codes
  category_slug: http-status-codes
  tags: "http,cors,cross-origin,security,preflight,access-control,same-origin"
  view_count: 34
  created_at: 1778695229
  updated_at: 1778695229
data:
  headers[9]{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[4]: "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]{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