1.3.19. /{db}/_security — Apache CouchDB® 3.5 Documentation

# 1.3.19. `/{db}/_security`

GET /{db}/_security

  Returns the current security object from the specified database.

  The security object consists of two compulsory elements, `admins` and `members`, which are used to specify the list of users and/or roles that have admin and members rights to the database respectively:

  - `members`: they can read all types of documents from the DB, and they can write (and edit) documents to the DB except for design documents.

  - `admins`: they have all the privileges of `members` plus the privileges: write (and edit) design documents, add/remove database admins and members and set the database revisions limit. They can not create a database nor delete a database.

  Both `members` and `admins` objects contain two array-typed fields:

  - `names`: List of CouchDB user names

  - `roles`: List of users roles

  Any additional fields in the security object are optional. The entire security object is made available to validation and other internal functions so that the database can control and limit functionality.

  If both the names and roles fields of either the admins or members properties are empty arrays, or are not existent, it means the database has no admins or members.

  Having no admins, only server admins (with the reserved `_admin` role) are able to update design documents and make other admin level changes.

  Having no members or roles, any user can write regular documents (any non-design document) and read documents from the database.

  Since CouchDB 3.x newly created databases have by default the _admin role to prevent unintentional access.

  If there are any member names or roles defined for a database, then only authenticated users having a matching name or role are allowed to read documents from the database (or do a `GET /{db}` call).

  Note

  If the security object for a database has never been set, then the value returned will be empty.

  Also note, that security objects are not regular versioned documents (that is, they are not under MVCC rules). This is a design choice to speed up authorization checks (avoids traversing a database’s documents B-Tree).

  Parameters:

    - db – Database name

  Request Headers:

    - Accept –

      - application/json

      - text/plain

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

  Response JSON Object:

    - admins (object) – Object with two fields as `names` and `roles`. See description above for more info.

    - members (object) – Object with two fields as `names` and `roles`. See description above for more info.

  Status Codes:

    - 200 OK – Request completed successfully

    - 401 Unauthorized – Unauthorized request to a protected API

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

  Request:

      GET /db/_security HTTP/1.1
      Accept: application/json
      Host: localhost:5984

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 109
      Content-Type: application/json
      Date: Mon, 12 Aug 2013 19:05:29 GMT
      Server: CouchDB (Erlang/OTP)

      {
          "admins": {
              "names": [
                  "superuser"
              ],
              "roles": [
                  "admins"
              ]
          },
          "members": {
              "names": [
                  "user1",
                  "user2"
              ],
              "roles": [
                  "developers"
              ]
          }
      }

PUT /{db}/_security

  Sets the security object for the given database.

  Parameters:

    - db – Database name

  Request Headers:

    - Accept –

      - application/json

      - text/plain

    - Content-Type – application/json

  Request JSON Object:

    - admins (object) – Object with two fields as `names` and `roles`. See description above for more info.

    - members (object) – Object with two fields as `names` and `roles`. See description above for more info.

  Response Headers:

    - Content-Type –

      - application/json

      - text/plain; charset=utf-8

  Response JSON Object:

    - ok (boolean) – Operation status

  Status Codes:

    - 200 OK – Request completed successfully

    - 401 Unauthorized – CouchDB Server Administrator privileges required

    - 403 Forbidden – Insufficient permissions / Too many requests with invalid credentials

  Request:

      shell> curl http://adm:pass@localhost:5984/pineapple/_security -X PUT -H 'content-type: application/json' -H 'accept: application/json' -d '{"admins":{"names":["superuser"],"roles":["admins"]},"members":{"names": ["user1","user2"],"roles": ["developers"]}}'

      PUT /db/_security HTTP/1.1
      Accept: application/json
      Content-Length: 121
      Content-Type: application/json
      Host: localhost:5984

      {
          "admins": {
              "names": [
                  "superuser"
              ],
              "roles": [
                  "admins"
              ]
          },
          "members": {
              "names": [
                  "user1",
                  "user2"
              ],
              "roles": [
                  "developers"
              ]
          }
      }

  Response:

      HTTP/1.1 200 OK
      Cache-Control: must-revalidate
      Content-Length: 12
      Content-Type: application/json
      Date: Tue, 13 Aug 2013 11:26:28 GMT
      Server: CouchDB (Erlang/OTP)

      {
          "ok": true
      }