Authors create and join documents: mutable key-value stores that multiple users read from, write to, and sync with, subscribing to live updates in real time.

a diagram of three author devices with arrows pointing to a document. the document is a table with key and value columns. for each row, the value column has an arrow pointing out to a blob


A document is a namespace that is uniquely identified by a keypair.

A key in a document is just a sequence of bytes. In practice keys are almost always UTF-8 strings. A value in a document is always a hash that points to a blob. Conceptually, a document looks like this when written in JSON notation:

  "bar": "bafkr4iebxyldaiwztn5kwt6bap5e5bnzeru5lgc64w6lns644ir6ky5soi",
  "bananas": "bafkr4ihr5vpp33v5ufos2dneywofls3gx67b5jmraxcn77odsu3yqcsohq",
  "foo": "bafkr4ic3ywkoq5k2bn7kaiz6lovehgkpfqk4kwstepcbs7pw256dtxutme",
  "slashes/are/also/ok": "bafkr4ic3ywkoq5k2bn7kaiz6lovehgkpfqk4kwstepcbs7pw256dtxutme",
  "so.are.dots": "bafkr4ic3ywkoq5k2bn7kaiz6lovehgkpfqk4kwstepcbs7pw256dtxutme",
  // ...

An entry in the document is a key-value pair. When an author writes an entry they first create a blob, then use the hash of the blob as the value, then pick a label to use as the key.

Authors & Permissions

Authors are users who have write access to a document. Every author has a keypair that represents their identity. The public side of a keypair identifies the user & validates the edits they make to the document, the private side of the keypair is used to sign edits.

The author that created the document is the document owner. The owner holds the private side of the document keypair and does not share it. Document owners have the ability to destroy the document and invite other authors to write to the document.

Granting read access to a document is as simple as sharing the document public key.


In iroh, the thing that links is the thing that syncs. Documents link together files

Document Identifiers

Documents are referred to within iroh by their document identifier or DocID. They look like this:

a document identifier


Document IDs are base32-lower serialization of the public key of the document. They do not change as the document changes.


Multiple Writers



Revocations & Key Rotations