2 files changed, 50 insertions, 0 deletions
diff --git a/docs/admin/engines/index.rst b/docs/admin/engines/index.rst
index 923b20a2b..02d6e604b 100644
--- a/docs/admin/engines/index.rst
+++ b/docs/admin/engines/index.rst
@@ -13,6 +13,7 @@ Engines & Settings
    :maxdepth: 1
 
    engine_settings
+   private-engines
    recoll
    sql-engines
    command-line-engines
diff --git a/docs/admin/engines/private-engines.rst b/docs/admin/engines/private-engines.rst
new file mode 100644
index 000000000..cc6ab2565
--- /dev/null
+++ b/docs/admin/engines/private-engines.rst
@@ -0,0 +1,49 @@
+.. _private engines:
+
+============================
+Private Engines (``tokens``)
+============================
+
+Administrators might find themselves wanting to limit access to some of the
+enabled engines on their instances. It might be because they do not want to
+expose some private information through :ref:`offline engines`.  Or they would
+rather share engines only with their trusted friends or colleagues.
+
+To solve this issue the concept of *private engines* exists.
+
+
+A new option was added to engines named `tokens`. It expects a list of
+strings. If the user making a request presents one of the tokens of an engine,
+they can access information about the engine and make search requests.
+
+Example configuration to restrict access to the Arch Linux Wiki engine:
+
+.. code:: yaml
+
+  - name: arch linux wiki
+    engine: archlinux
+    shortcut: al
+    tokens: [ 'my-secret-token' ]
+
+
+Unless a user has configured the right token, the engine is going
+to be hidden from him/her. It is not going to be included in the
+list of engines on the Preferences page and in the output of
+`/config` REST API call.
+
+Tokens can be added to one's configuration on the Preferences page
+under "Engine tokens". The input expects a comma separated list of
+strings.
+
+The distribution of the tokens from the administrator to the users
+is not carved in stone. As providing access to such engines
+implies that the admin knows and trusts the user, we do not see
+necessary to come up with a strict process. Instead,
+we would like to add guidelines to the documentation of the feature.
+
+
+Acknowledgment
+==============
+
+This development was sponsored by `Search and Discovery Fund
+<https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_.