From 2074efa5a49f72cf1c47c28894de6c0b1f0fb3b1 Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Thu, 4 Jun 2020 18:38:32 -0700
Subject: [PATCH] Another actor_from_request example

---
 docs/plugins.rst | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/plugins.rst b/docs/plugins.rst
index 3777bba7..8004e118 100644
--- a/docs/plugins.rst
+++ b/docs/plugins.rst
@@ -957,6 +957,27 @@ This is part of Datasette's :ref:`authentication and permissions system <authent
 
 If it cannot authenticate an actor, it should return ``None``. Otherwise it should return a dictionary representing that actor.
 
+Here's an example that authenticates the actor based on an incoming API key:
+
+.. code-block:: python
+
+    from datasette import hookimpl
+    import secrets
+
+    SECRET_KEY = "this-is-a-secret"
+
+    @hookimpl
+    def actor_from_request(datasette, request):
+        authorization = request.headers.get("authorization") or ""
+        expected = "Bearer {}".format(SECRET_KEY)
+
+        if secrets.compare_digest(authorization, expected):
+            return {"id": "bot"}
+
+If you install this in your plugins directory you can test it like this::
+
+    $ curl -H 'Authorization: Bearer this-is-a-secret' http://localhost:8003/-/actor.json
+
 Instead of returning a dictionary, this function can return an awaitable function which itself returns either ``None`` or a dictionary. This is useful for authentication functions that need to make a database query - for example:
 
 .. code-block:: python