Authentication

There are several ways to authenticate on the API.

Basic Auth

We recommend basic auth only in development mode or when writing simple scripts (the kind that does not do more than 5 requests). Because this is a slow form of authentication.

GET /_session HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json

The output is:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "ok": true,
  "userCtx": {
    "name": "usr-9fcc027ca99e44468227bef4c4440d5c",
    "roles": [
      "acc-1e36d77db5434f3cbded1bb07db403c1"
    ]
  }
}

Bearer Token

Getting a token means you authenticate with a slow process, and after that you only use the token.

Using username and password is slow because we have algorithms in place to prevent Timing attacks

Although, we don’t have yet a mechanism to expire all of the tokens created by a user we plan to implement it. This is another reason you should prefer to use a token to authenticate.

The endpoint to get a token is POST /_session.

Here you can use Basic Auth for the request:

POST /_session HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json

Or add the information within the JSON payload:

POST /_session HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "username": "[email protected]",
  "password": "password"
}

In both cases the JSON output is:

HTTP/1.1 200 OK
Content-Type: application/json
set-cookie: AuthSession=eyJhbGciOi; path=/; expires=Wed, 08 Feb 2023 17:59:47 GMT; HttpOnly; SameSite=Strict
{
  "ok": true,
  "name": "usr-9fcc027ca99e44468227bef4c4440d5c",
  "roles": [
    "acc-1e36d77db5434f3cbded1bb07db403c1"
  ]
}

The JWT token is in the header of the HTTP request as set-cookie.

To simplify the output and commands we are going to shorten the token from eyJhbGciOi.eyJ1c2VyX2lkIjoiOWZjYzAyN2MtYTk5ZS00NDQ2LTgyMjctYmVmNGM0NDQwZDVjIn0.7GzetforEg8U1-PrsjWNELa2iMaEsD1JJNoY82vh52s to eyJhbGciOi.

With that token you can use to authenticate the following requests.

For example, to get your session with that token:

GET /_session HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

And the output is the same as before:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "ok": true,
  "name": "usr-9fcc027ca99e44468227bef4c4440d5c",
  "roles": [
    "acc-1e36d77db5434f3cbded1bb07db403c1"
  ]
}

Here is an explanation of the attributes:

ok
Indicates the authentication is ok. If this is a POST request the token is expected to be in the header.
name
This is the unique ID of the user
roles
roles exposes an array with the databases the user has some kind of permission, be it read and/or write.

Session

GET /_session

Request:

GET /_session HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "ok": true,
  "name": "usr-9fcc027ca99e44468227bef4c4440d5c",
  "roles": [
    "acc-1e36d77db5434f3cbded1bb07db403c1"
  ]
}

And the response in case of wrong token or username/password:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "error": "unauthorized",
  "reason": "Name or password is incorrect."
}

Database

Database is what the frontend displays as Group. For the purpose of this documentation we are going to call database.

A database is basically an aggregation of data that several users have access to. Some other software may call it Group, Organization, or Team.

Database and User are the only two things that do not depend on anything to exist.

As you could see in the session output, the roles attribute exposes an array with the unique name of each database the user has permission.

Each user can create up to 5 free databases, we recommend using this feature to test any API integration.

GET /:db_name

Request:

GET /acc-1e36d77db5434f3cbded1bb07db403c1 HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "instance_start_time": "0",
  "db_name": "acc-afb2ce55bfdf489088273a1ab8511936",
  "update_seq": "18-1700000000",
  "doc_count": 0
}

CRUD operations

Besides that we also have one kind of record that let you perform tests in the API even in a production environment.

There is no frontend to see any of the data within the Crystal records, e.g., this is an API-only feature.

This kind of record lets you manage Crystal, each has the following fields:

  • _id: Unique ID of the record
  • _rev: The locking code lets you perform updates, auto generated
  • klass: The kind/type of record, in this case, Crystal
  • name: The name of the Crystal, because this is a testing endpoint, there is no right or wrong information to store here, but it cannot be an empty string, Text
  • age: The age of the Crystal, the number stored in this field has to be lower than 125, Integer

POST /:db_name - Create One Record

When you sign up your database and the _id of your User are random, we do that to prevent databases and Users to reuse _ids as this can lead to security vulnerabilities.

But when you manage the records within your organization you must provide the _id yourself.

As you could see from the previous examples the _id field is a Universally unique identifier plus a 3 letter prefix for that particular kind of record.

If you don’t want to use a random _id for your records but an incremental one, you can replace all characters with 0 except for the prefix and the - (dash) and place the number to the end, example:

crs-00000000000000000000000000000157

Creating a record with valid data:

POST /acc-1e36d77db5434f3cbded1bb07db403c1 HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

{
  "_id": "crs-041fa18a2f77410d9bf4e07fa33abeeb",
  "klass": "Crystal",
  "name": "John Doe",
  "age": 120
}

Returns:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "crs-a9d89d7963a2ee2f1b92f73c2dfb73a0",
  "ok": true,
  "rev": "1-d89d7963a2ee2f1b92f73c2dfb73a0"
}

Creating a record with missing mandatory field:

POST /acc-1e36d77db5434f3cbded1bb07db403c1 HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

{
  "name": "John Doe",
  "age": 120
}

Returns:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
  "error": "unprocessable_entity",
  "reason": {
    "_id": "can't be blank"
  }
}

Creating a record with invalid data:

POST /acc-1e36d77db5434f3cbded1bb07db403c1 HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

{
  "_id": "crs-ee4371b193ac4b4191cb27624c7442c2",
  "name": "John Doe",
  "age": 210
}

Returns:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
  "error": "unprocessable_entity",
  "reason": {
    "age": "less-than-or-equal-to"
  }
}

GET /:db_name/:doc_id - Get one record

With the ID of the record to query you can call the API with:

GET /acc-1e36d77db5434f3cbded1bb07db403c1/crs-ee4371b193ac4b4191cb27624c7442c2 HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

Returns:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "_id": "crs-a9d89d7963a2ee2f1b92f73c2dfb73a0",
  "_rev": "1-10257bd481d47fa40decc71cdbea0928",
  "klass": "Crystal",
  "name": "John Doe",
  "age": 120
}

PUT /:db_name/:doc_id - Update one record

Some rules are mandatory to this endpoint:

  • You have to provide a valid rev in the query parameters
  • The document is fully replaced with the body of the request

An example of updating a Crystal:

PUT /acc-1e36d77db5434f3cbded1bb07db403c1/crs-ee4371b193ac4b4191cb27624c7442c2?rev=1-25907e94b8cec1aa102595d415fbb36b HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

{
  "klass": "Crystal",
  "name": "John Doe",
  "age":120
}

And the response is the same as the POST:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "crs-ee4371b193ac4b4191cb27624c7442c2",
  "ok": true,
  "rev": "2-51e28e113e600bc19bff2dea57fe45ed"
}

DELETE /:db_name/:doc_id - Delete one record

You also need the rev query parameters to delete a record.

An example request to delete a record is:

DELETE /acc-1e36d77db5434f3cbded1bb07db403c1/crs-ee4371b193ac4b4191cb27624c7442c2?rev=2-f32d250e7d4ce0a07c99dd2d14095582 HTTP/1.1
Authorization: Bearer eyJhbGciOi
Content-Type: application/json
Accept: application/json

And the response is the same as create or update:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "crs-ee4371b193ac4b4191cb27624c7442c2",
  "ok": true,
  "rev": "3-1cf191e2a26ce6f2648dcf52c7bb676e"
}

If you forget or pass on a wrong rev you get the same response as before:

HTTP/1.1 409 Conflict
Content-Type: application/json
{
  "error": "conflict",
  "reason": "Document update conflict."
}

Extra operations

POST /:db_name/_find

Use this endpoint only to find multiple records by a given type.

Parameters (in the request body):

  • fields, array of strings, optional, returns all fields in case it is not specified
  • limit, integer, optional, the number of results to return, use together with skip to paginate
  • skip, integer, optional, the number of results to skip, use together with limit to paginate
  • sort, array of objects, mandatory, always sort by label or updated_at
  • selector: object, mandatory, the selector for the request, always include klass

See CouchDB’s documentation about the _find endpoint for more information and examples.

Request:

PROPFIND /acc-1e36d77db5434f3cbded1bb07db403c1/_find
Content-Type: application/json
Accept: application/json

{
  "fields": ["_id", "label"],
  "limit": 10,
  "skip": 0,
  "sort": [{"label": "desc"}],
  "selector": {
    "klass": "Crystal"
  }
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "docs": [
    {
      "_id": "crs-041fa18a2f77410d9bf4e07fa33abeeb",
      "_rev": "1-dc89f3bff092c74be193fceaddb03272",
      "klass": "Crystal",
      "name": "John Doe",
      "age": 120
    }
  ],
  "bookmark": "g1AAAAB"
}

POST /:db_name/_design/search-index2/_nouveau/fts

Use this endpoint only to perform full-text search on the database.

In the request body, you must include q, and inside that q you must include klass and search, see example below.

Request:

PROPFIND /acc-1e36d77db5434f3cbded1bb07db403c1/_design/search-index2/_nouveau/fts
Content-Type: application/json
Accept: application/json

{
  "include_docs": true,
  "limit": 2,
  "skip": 2,
  "sort": "label",
  "q": "klass:Crystal AND search:test1"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "total_hits": 1,
  "hits": [
    {
      "id": "crs-041fa18a2f77410d9bf4e07fa33abeeb",
      "doc": {
        "_id": "crs-041fa18a2f77410d9bf4e07fa33abeeb",
        "_rev": "1-dc89f3bff092c74be193fceaddb03272",
        "klass": "Crystal",
        "name": "John Doe",
        "age": 120
      }
    }
  ],
  "bookmark": "W1t7InZ"
}

WebDAV

We also implement a WebDAV API for you to manage your files.

PROPFIND /

Querying the root of the website only requests one item, see the next section.

Request:

PROPFIND /
Content-Type: application/xml
Accept: application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<D:multistatus xmlns:D="DAV:" xmlns:A="http://standardn9.com/webdav">
  <D:response>
    <D:href>/</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname></D:displayname>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/_webdav/</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname>_webdav</D:displayname>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

PROPFIND /_webdav/

Returns the list of database the user can access.

By default it returns with the handle of the database, not with the database name, this way it is easier for humans to identify the Group.

Request:

PROPFIND /_webdav/
Content-Type: application/xml
Accept: application/xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<D:multistatus xmlns:D="DAV:" xmlns:A="http://standardn9.com/webdav">
  <D:response>
    <D:href>/_webdav/</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname>_webdav</D:displayname>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/_webdav/hardware-t7mjw/</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname>hardware-t7mjw</D:displayname>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/_webdav/test-2bs/</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname>test-2bs</D:displayname>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

PROPFIND /_webdav/:handle/

This endpoint is where the list of files for each database starts.

Request:

PROPFIND /_webdav/hardware-t7mjw/
Accept: application/xml

Response:

HTTP/1.1 207 Multi-Status
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<D:multistatus xmlns:D="DAV:" xmlns:A="http://standardn9.com/webdav">
  <D:response>
    <D:href>/_webdav/hardware-t7mjw/</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname></D:displayname>
        <D:creationdate/>
        <D:getlastmodified/>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/_webdav/hardware-t7mjw/pwd.txt</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname>pwd.txt</D:displayname>
        <D:creationdate>Thu, 25 Jun 2026 16:08:33 GMT</D:creationdate>
        <D:getlastmodified>Thu, 25 Jun 2026 16:08:33 GMT</D:getlastmodified>
        <D:getcontentlength>9</D:getcontentlength>
        <D:resourcetype>
        </D:resourcetype>
        <A:system-id>fle-eda30114a4874349a42615837035ef14</A:system-id>
        <A:system-rev>2-d026b08b7db15661a419d339d8a094e5</A:system-rev>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
  <D:response>
    <D:href>/_webdav/hardware-t7mjw/test/</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname>test</D:displayname>
        <D:creationdate>Thu, 25 Jun 2026 17:06:11 GMT</D:creationdate>
        <D:getlastmodified>Thu, 25 Jun 2026 17:06:21 GMT</D:getlastmodified>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
        <A:system-id>fle-3e0a0640c8204c798b0b0a06b876038e</A:system-id>
        <A:system-rev>2-1d97126853766068141a1df4b0242ff9</A:system-rev>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

In this example there is one folder and one file.

PROPFIND /_webdav/:handle/somecol/

Request:

PROPFIND /_webdav/hardware-t7mjw/test/
Accept: application/xml

Response:

HTTP/1.1 207 Multi-Status
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<D:multistatus xmlns:D="DAV:" xmlns:A="http://standardn9.com/webdav">
  <D:response>
    <D:href>/_webdav/hardware-t7mjw/test/</D:href>
    <D:propstat>
      <D:prop>
        <D:displayname>test</D:displayname>
        <D:creationdate>Thu, 25 Jun 2026 15:42:41 GMT</D:creationdate>
        <D:getlastmodified>Thu, 25 Jun 2026 15:42:41 GMT</D:getlastmodified>
        <D:resourcetype>
          <D:collection/>
        </D:resourcetype>
        <A:system-id>fle-b725ea89059e403c8bfbdc0259037d02</A:system-id>
        <A:system-rev>1-f4bcedc8d4ed9d7a960271009c96a77a</A:system-rev>
      </D:prop>
      <D:status>HTTP/1.1 200 OK</D:status>
    </D:propstat>
  </D:response>
</D:multistatus>

In this example the folder is empty.

References