API: Encoding of Zettel Access Rights

00001012921200 · Info · (manual) · #api #manual #reference #zettelstore

Various API calls return a JSON key "rights" that encodes the access rights the user currently has. It is an integer number between 0 and 62.1

The value 0 signals that something went wrong internally while determining the access rights.

A value of 1 says, that the current user has no access right for the given zettel. In most cases, this value will not occur, because only zettel are presented, which are at least readable by the current user.

Values 2 to 62 are binary encoded values, where each bit signals a special right.

Bit numberBit valueMeaning
12User is allowed to create a new zettel
24User is allowed to read the zettel
38User is allowed to update the zettel
416User is allowed to rename the zettel
532User is allowed to delete the zettel

The algorithm to calculate the actual access rights from the value is relatively simple:

  1. Search for the biggest bit value that is less than the rights value. This is an access right for the current user.
  2. Subtract the bit value from the rights value. Remember the difference as the new rights value.
  3. If it is greater than zero, move to step 1.

As an example, let's assume a rights value of 42:

  1. The first right is the right to delete a zettel. The new value of the rights value is now 10 (42-32).
  2. The next right is the right to update a zettel (16 > 10, but 8 < 10). The new value of the rights value is now 2 (10-8).
  3. The last right is the right to create a new zettel. The rights value is now zero, the algorithm ends.

In practice, not every rights value will occur. A Zettelstore in read-only mode will always return the value 4. Similar, a Zettelstore that you started with a double-click will return either the value 6 (reading and updating) or the value 62 (all operations are allowed).

If you have added an additional user to your Zettelstore, this might change. The access rights are calculated depending on enabled authentication, on the user role of the current user, on visibility rules for a given zettel and on the read-only status for the zettel.

  1. Not all values in this range are used. ↩︎