We have a new wiki. The migration is not 100% complete. You can help out by moving pages across. This wiki will exist for as long as there are pages left.

The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

Note: CORS is supported only in CouchDB 1.3.x branches or releases, and at present is experimental support. This means that:

WARNING!! This page is a temporary gathering spot for CORS documentation while the git branch is in development. It will get merged back into the cors branch when sufficiently clean, and will use the sphinx support being worked on in the docs branch.

Introducing CORS

By supporting CORS functionality, a CouchDB instance can accept direct connections to protected DBs and instances, without the browser functionality being blocked due to the same origin constraint. CORS is widely supported today on over 90% of browsers.



Enabling CORS

To enable CORS support, you need to set the option enable_cors = true in the [httpd] section of local.ini, and [cors] section with origins = *. Note that by default, no origins are accepted, you must either use a wildcard or whitelist.

enable_cors = true

origins = *

Tightening Access

Restricting by Protocol, Host and optional Port

; List of origins, separated by a comma (protocol, host, port)
; refer to http://tools.ietf.org/html/rfc6454 for specification
origins = http://home.muse.net.nz:8000, https://localhost, http://www.number10.gov.uk:80

Restricting Accepted Methods

; List of accepted methods, comma-separated
; refer to http://tools.ietf.org/html/rfc2616, rfc2817, rfc5789
methods = GET, POST, PUT, DELETE

Restricting Accepted Headers

; List of accepted headers separated by a comma
headers = TODO

Securing at the VHOST level


To set the options for a vhost, you will need to create a section with the vhost name prefixed by "cors:" . Ex for the vhost example.com:

; Configuration for a vhost
; credentials = false
; List of origins separated by a comma
;origins =
; List of accepted headers separated by a comma
; headers =
; List of accepted methods
; methods =



Testing Your Implementation

The following snippet was lifted from html5rocks CORS tutorial:

<!DOCTYPE html>
<html lang="en">
    <title>Testing CORS</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
    <meta author="http://www.html5rocks.com/en/tutorials/cors/#toc-adding-cors-support-to-the-server">
    <meta license="Apache 2.0">
      // Create the XHR object.
      function createCORSRequest(method, url) {
        var xhr = new XMLHttpRequest();
        if ("withCredentials" in xhr) {
          // XHR for Chrome/Firefox/Opera/Safari.
          xhr.open(method, url, true);
        } else if (typeof XDomainRequest != "undefined") {
          // XDomainRequest for IE.
          xhr = new XDomainRequest();
          xhr.open(method, url);
        } else {
          // CORS not supported.
          xhr = null;
        return xhr;

      // Make the actual CORS request.
      function makeCorsRequest(uri) {
        console.log("got uri: " + uri);
        var xhr = createCORSRequest('GET', uri);
        if (!xhr) {
          alert('CORS not supported');

        // Response handlers.
        xhr.onload = function() {
          console.log('Response from CORS request to ' + uri + ': ' + xhr.responseText);

        xhr.onerror = function() {
          console.log('Woops, there was an error making the request to ' + uri + '.');

      $(document).ready(function() {

Reference Material

This image is from the excellent html5rocks CORS tutorial.


CORS References

Client-side CORS support and usage

Note that at least IE >= 8 does not support pre-flight.