This
cross-origin sharing standard
can enable cross-origin HTTP requests for:
Invocations of
fetch()
or
XMLHttpRequest
, as discussed above.
Web Fonts (for cross-domain font usage in
@font-face
within CSS), as described in the
font fetching requirements
, so that servers can deploy TrueType fonts that can only be loaded cross-origin and used by websites that are permitted to do so.
WebGL textures
Images/video frames drawn to a canvas using
drawImage()
CSS Shapes from images.
This is a general article about Cross-Origin Resource Sharing and includes a discussion of the necessary HTTP headers.
The Cross-Origin Resource Sharing standard works by adding new
HTTP headers
that let servers describe which origins are permitted to read that information from a web browser. Additionally, for HTTP request methods that can cause side-effects on server data (in particular, HTTP methods other than
GET
, or
POST
with certain
MIME types
), the specification mandates that browsers "preflight" the request, soliciting supported methods from the server with the HTTP
OPTIONS
request method, and then, upon "approval" from the server, sending the actual request. Servers can also inform clients whether "credentials" (such as
and
HTTP Authentication
) should be sent with requests.
CORS failures result in errors but for security reasons, specifics about the error
are not available to JavaScript
. All the code knows is that an error occurred. The only way to determine what specifically went wrong is to look at the browser's console for details.
Subsequent sections discuss scenarios, as well as provide a breakdown of the HTTP headers used.
We present three scenarios that demonstrate how Cross-Origin Resource Sharing works. All these examples use
fetch()
, which can make cross-origin requests in any supporting browser.
Some requests don't trigger a
CORS preflight
. Those are called
simple requests
from the obsolete
CORS spec
, though the
Fetch spec
(which now defines CORS) doesn't use that term.
The motivation is that the


element from HTML 4.0 (which predates cross-site
fetch()
and
XMLHttpRequest
) can submit simple requests to any origin, so anyone writing a server must already be protecting against
cross-site request forgery
(CSRF). Under this assumption, the server doesn't have to opt-in (by responding to a preflight request) to receive any request that looks like a form submission, since the threat of CSRF is no worse than that of form submission. However, the server still must opt-in using
Access-Control-Allow-Origin
to
share
the response with the script.
simple request
is one that
meets all the following conditions
Note:
WebKit Nightly and Safari Technology Preview place additional restrictions on the values allowed in the
Accept
Accept-Language
, and
Content-Language
headers. If any of those headers have "nonstandard" values, WebKit/Safari does not consider the request to be a "simple request". What values WebKit/Safari consider "nonstandard" is not documented, except in the following WebKit bugs:
No other browsers implement these extra restrictions because they're not part of the spec.
For example, suppose web content at
wishes to fetch JSON content from domain
. Code of this sort might be used in JavaScript deployed on
foo.example
js
const fetchPromise = fetch("https://bar.other");

fetchPromise
.then((response) => response.json())
.then((data) => {
console.log(data);
});
This operation performs a simple exchange between the client and the server, using CORS headers to handle the privileges:
Let's look at what the browser will send to the server in this case:
http
GET /resources/public-data/ HTTP/1.1
Host: bar.other
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Connection: keep-alive
Origin: https://foo.example
The request header of note is
Origin
, which shows that the invocation is coming from
Now let's see how the server responds:
http
HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 00:23:53 GMT
Server: Apache/2
Access-Control-Allow-Origin: *
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
Transfer-Encoding: chunked
Content-Type: application/xml

[…XML Data…]
In response, the server returns an
Access-Control-Allow-Origin
header with
Access-Control-Allow-Origin: *
, which means that the resource can be accessed by
any
origin.
http
Access-Control-Allow-Origin: *
This pattern of the
Origin
and
Access-Control-Allow-Origin
headers is the simplest use of the access control protocol. If the resource owners at
wished to restrict access to the resource to requests
only
from
(i.e., no domain other than
can access the resource in a cross-origin manner), they would send:
http
Access-Control-Allow-Origin: https://foo.example
Note:
When responding to a
credentialed requests
request, the server
must
specify an origin in the value of the
Access-Control-Allow-Origin
header, instead of specifying the
wildcard.
Unlike
simple requests
, for "preflighted" requests the browser first sends an HTTP request using the
OPTIONS
method to the resource on the other origin, in order to determine if the actual request is safe to send. Such cross-origin requests are preflighted since they may have implications for user data.
The following is an example of a request that will be preflighted:
js
const fetchPromise = fetch("https://bar.other/doc", {
method: "POST",
mode: "cors",
headers: {
"Content-Type": "text/xml",
"X-PINGOTHER": "pingpong",
},
body: "Arun",
});

fetchPromise.then((response) => {
console.log(response.status);
});
The example above creates an XML body to send with the
POST
request. Also, a non-standard HTTP
X-PINGOTHER
request header is set. Such headers are not part of HTTP/1.1, but are generally useful to web applications. Since the request uses a
Content-Type
of
text/xml
, and since a custom header is set, this request is preflighted.
Note:
As described below, the actual
POST
request does not include the
Access-Control-Request-*
headers; they are needed only for the
OPTIONS
request.
Let's look at the full exchange between client and server. The first exchange is the
preflight request/response
http
OPTIONS /doc HTTP/1.1
Host: bar.other
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Connection: keep-alive
Origin: https://foo.example
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type,x-pingother

HTTP/1.1 204 No Content
Date: Mon, 01 Dec 2008 01:15:39 GMT
Server: Apache/2
Access-Control-Allow-Origin: https://foo.example
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
Access-Control-Max-Age: 86400
Vary: Accept-Encoding, Origin
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
The first block above represents the preflight request with the
OPTIONS
method. The browser determines that it needs to send this based on the request parameters that the JavaScript code snippet above was using, so that the server can respond whether it is acceptable to send the request with the actual request parameters. OPTIONS is an HTTP/1.1 method that is used to determine further information from servers, and is a
safe
method, meaning that it can't be used to change the resource. Note that along with the OPTIONS request, two other request headers are sent:
http
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type,x-pingother
The
Access-Control-Request-Method
header notifies the server as part of a preflight request that when the actual request is sent, it will do so with a
POST
request method. The
Access-Control-Request-Headers
header notifies the server that when the actual request is sent, it will do so with
X-PINGOTHER
and
Content-Type
custom headers. Now the server has an opportunity to determine whether it can accept a request under these conditions.
The second block above is the response that the server returns, which indicate that the request method (
POST
) and request headers (
X-PINGOTHER
) are acceptable. Let's have a closer look at the following lines:
http
Access-Control-Allow-Origin: https://foo.example
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
Access-Control-Max-Age: 86400
The server responds with
Access-Control-Allow-Origin: https://foo.example
, restricting access to the requesting origin domain only. It also responds with
Access-Control-Allow-Methods
, which says that
POST
and
GET
are valid methods to query the resource in question (this header is similar to the
Allow
response header, but used strictly within the context of access control).
The server also sends
Access-Control-Allow-Headers
with a value of
X-PINGOTHER, Content-Type
, confirming that these are permitted headers to be used with the actual request. Like
Access-Control-Allow-Methods
Access-Control-Allow-Headers
is a comma-separated list of acceptable headers.
Finally,
Access-Control-Max-Age
gives the value in seconds for how long the response to the preflight request can be cached without sending another preflight request. The default value is 5 seconds. In the present case, the max age is 86400 seconds (= 24 hours). Note that each browser has a
maximum internal value
that takes precedence when the
Access-Control-Max-Age
exceeds it.
Once the preflight request is complete, the real request is sent:
http
POST /doc HTTP/1.1
Host: bar.other
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Connection: keep-alive
X-PINGOTHER: pingpong
Content-Type: text/xml; charset=UTF-8
Referer: https://foo.example/examples/preflightInvocation.html
Content-Length: 55
Origin: https://foo.example
Pragma: no-cache
Cache-Control: no-cache

Arun

HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:15:40 GMT
Server: Apache/2
Access-Control-Allow-Origin: https://foo.example
Vary: Accept-Encoding, Origin
Content-Encoding: gzip
Content-Length: 235
Keep-Alive: timeout=2, max=99
Connection: Keep-Alive
Content-Type: text/plain

[Some XML content]
Preflighted requests and redirects
Not all browsers currently support following redirects after a preflighted request. If a redirect occurs after such a request, some browsers currently will report an error message such as the following:
The request was redirected to
, which is disallowed for cross-origin requests that require preflight.
Request requires preflight, which is disallowed to follow cross-origin redirects.
The CORS protocol originally required that behavior but
was subsequently changed to no longer require it
. However, not all browsers have implemented the change, and thus still exhibit the originally required behavior.
Until browsers catch up with the spec, you may be able to work around this limitation by doing one or both of the following:
Change the server-side behavior to avoid the preflight and/or to avoid the redirect
Change the request such that it is a
simple request
that doesn't cause a preflight
If that's not possible, then another way is to:
Make a
simple request
(using
Response.url
for the Fetch API, or
XMLHttpRequest.responseURL
) to determine what URL the real preflighted request would end up at.
Make another request (the
real
request) using the URL you obtained from
Response.url
or
XMLHttpRequest.responseURL
in the first step.
However, if the request is one that triggers a preflight due to the presence of the
Authorization
header in the request, you won't be able to work around the limitation using the steps above. And you won't be able to work around it at all unless you have control over the server the request is being made to.
Note:
When making credentialed requests to a different domain, third-party cookie policies will still apply. The policy is always enforced regardless of any setup on the server and the client as described in this chapter.
The most interesting capability exposed by both
fetch()
or
XMLHttpRequest
and CORS is the ability to make "credentialed" requests that are aware of
HTTP cookies
and HTTP Authentication information. By default, in cross-origin
fetch()
or
XMLHttpRequest
calls, browsers will
not
send credentials.
To ask for a
fetch()
request to include credentials, set the
credentials
option to
"include"
To ask for an
XMLHttpRequest
request to include credentials, set the
XMLHttpRequest.withCredentials
property to
true
In this example, content originally loaded from
makes a GET request to a resource on
which sets Cookies. Content on foo.example might contain JavaScript like this:
js
const url = "https://bar.other/resources/credentialed-content/";

const request = new Request(url, { credentials: "include" });

const fetchPromise = fetch(request);
fetchPromise.then((response) => console.log(response));
This code creates a
Request
object, setting the
credentials
option to
"include"
in the constructor, then passes this request into
fetch()
. Since this is a simple
GET
request, it is not preflighted but the browser will
reject
any response that does not have the
Access-Control-Allow-Credentials
header set to
true
, and
not
make the response available to the invoking web content.
Here is a sample exchange between client and server:
http
GET /resources/credentialed-content/ HTTP/1.1
Host: bar.other
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-us,en;q=0.5
Accept-Encoding: gzip,deflate
Connection: keep-alive
Referer: https://foo.example/examples/credential.html
Origin: https://foo.example
Cookie: pageAccess=2

HTTP/1.1 200 OK
Date: Mon, 01 Dec 2008 01:34:52 GMT
Server: Apache/2
Access-Control-Allow-Origin: https://foo.example
Access-Control-Allow-Credentials: true
Cache-Control: no-cache
Pragma: no-cache
Set-Cookie: pageAccess=3; expires=Wed, 31-Dec-2008 01:34:53 GMT
Vary: Accept-Encoding, Origin
Content-Encoding: gzip
Content-Length: 106
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
Content-Type: text/plain

[text/plain content]
Although the request's
header contains the cookie destined for the content on
, if bar.other did not respond with an
Access-Control-Allow-Credentials
with value
true
, as demonstrated in this example, the response would be ignored and not made available to the web content.
Preflight requests and credentials
CORS-preflight requests must never include credentials. The
response
to a preflight request must specify
Access-Control-Allow-Credentials: true
to indicate that the actual request can be made with credentials.
Note:
Some enterprise authentication services require that TLS client certificates be sent in preflight requests, in contravention of the
Fetch
specification.
Firefox 87 allows this non-compliant behavior to be enabled by setting the preference:
network.cors_preflight.allow_client_cert
to
true
Firefox bug 1511151
). Chromium-based browsers currently always send TLS client certificates in CORS preflight requests (
Chrome bug 775438
).
Credentialed requests and wildcards
When responding to a credentialed request:
The server
must not
specify the
wildcard for the
Access-Control-Allow-Origin
response-header value, but must instead specify an explicit origin; for example:
Access-Control-Allow-Origin: https://example.com
The server
must not
specify the
wildcard for the
Access-Control-Allow-Headers
response-header value, but must instead specify an explicit list of header names; for example,
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
The server
must not
specify the
wildcard for the
Access-Control-Allow-Methods
response-header value, but must instead specify an explicit list of method names; for example,
Access-Control-Allow-Methods: POST, GET
The server
must not
specify the
wildcard for the
Access-Control-Expose-Headers
response-header value, but must instead specify an explicit list of header names; for example,
Access-Control-Expose-Headers: Content-Encoding, Kuma-Revision
If a request includes a credential (most commonly a
header) and the response includes an
Access-Control-Allow-Origin: *
header (that is, with the wildcard), the browser will block access to the response, and report a CORS error in the devtools console.
But if a request does include a credential (like the
header) and the response includes an actual origin rather than the wildcard (like, for example,
Access-Control-Allow-Origin: https://example.com
), then the browser will allow access to the response from the specified origin.
Also note that any
Set-Cookie
response header in a response would not set a cookie if the
Access-Control-Allow-Origin
value in that response is the
wildcard rather an actual origin.
Third-party cookies
Note that cookies set in CORS responses are subject to normal third-party cookie policies. In the example above, the page is loaded from
foo.example
but the
Set-Cookie
header in the response is sent by
bar.other
, and would thus not be saved if the user's browser is configured to reject all third-party cookies.
Cookies set in CORS requests and responses are subject to normal third-party cookie policies.
Third-party cookie policies may prevent third party cookies being sent in requests, effectively stopping a site from making credentialed requests even if permitted by the third party server (using
Access-Control-Allow-Credentials
).
The default policy differs between browsers, but may be set using the
SameSite
attribute.
Even if credentialed requests are allowed, a browser may be configured to reject all third-party cookies in responses.
This section lists the HTTP response headers that servers return for access control requests as defined by the Cross-Origin Resource Sharing specification. The previous section gives an overview of these in action.
A returned resource may have one
Access-Control-Allow-Origin
header with the following syntax:
http
Access-Control-Allow-Origin: | *
Access-Control-Allow-Origin
specifies either a single origin which tells browsers to allow that origin to access the resource; or else — for requests
without
credentials — the
wildcard tells browsers to allow any origin to access the resource.
For example, to allow code from the origin
to access the resource, you can specify:
http
Access-Control-Allow-Origin: https://mozilla.org
Vary: Origin
If the server specifies a single origin (that may dynamically change based on the requesting origin as part of an allowlist) rather than the
wildcard, then the server should also include
Origin
in the
Vary
response header to indicate to clients that server responses will differ based on the value of the
Origin
request header.
The
Access-Control-Expose-Headers
header adds the specified headers to the allowlist that JavaScript (such as
Response.headers
) in browsers is allowed to access.
http
Access-Control-Expose-Headers: [, ]*
For example, the following would allow the
X-My-Custom-Header
and
X-Another-Custom-Header
headers to be exposed to the browser:
http
Access-Control-Expose-Headers: X-My-Custom-Header, X-Another-Custom-Header
The
Access-Control-Max-Age
header indicates how long the results of a preflight request can be cached. For an example of a preflight request, see the above examples.
http
Access-Control-Max-Age:
The
delta-seconds
parameter indicates the number of seconds the results can be cached.
The
Access-Control-Allow-Credentials
header indicates whether or not the response to the request can be exposed when the
credentials
flag is true. When used as part of a response to a preflight request, this indicates whether or not the actual request can be made using credentials. Note that simple
GET
requests are not preflighted, and so if a request is made for a resource with credentials, if this header is not returned with the resource, the response is ignored by the browser and not returned to web content.
http
Access-Control-Allow-Credentials: true
Credentialed requests
are discussed above.
The
Access-Control-Allow-Methods
header specifies the method or methods allowed when accessing the resource. This is used in response to a preflight request. The conditions under which a request is preflighted are discussed above.
http
Access-Control-Allow-Methods: [, ]*
An example of a
preflight request
is given above, including an example which sends this header to the browser.
The
Access-Control-Allow-Headers
header is used in response to a
preflight request
to indicate which HTTP headers can be used when making the actual request. This header is the server side response to the browser's
Access-Control-Request-Headers
header.
http
Access-Control-Allow-Headers: [, ]*
This section lists headers that clients may use when issuing HTTP requests in order to make use of the cross-origin sharing feature. Note that these headers are set for you when making invocations to servers. Developers making cross-origin requests do not have to set any cross-origin sharing request headers programmatically.
The
Origin
header indicates the origin of the cross-origin access request or preflight request.
The origin is a URL indicating the server from which the request is initiated. It does not include any path information, only the server name.
Note:
The
origin
value can be
null
Note that in any access control request, the
Origin
header is
always
sent.
The
Access-Control-Request-Method
is used when issuing a preflight request to let the server know what HTTP method will be used when the actual request is made.
http
Access-Control-Request-Method:
Examples of this usage can be
found above.
The
Access-Control-Request-Headers
header is used when issuing a preflight request to let the server know what HTTP headers will be used when the actual request is made (for example, by passing them as the
headers
option). This browser-side header will be answered by the complementary server-side header of
Access-Control-Allow-Headers
http
Access-Control-Request-Headers: [,]*
Examples of this usage can be
found above