Improved permissions documentation

docs/authentication.rst

@@ -47,6 +47,13 @@ The URL on the first line includes a one-use token which can be used to sign in
         "id": "root"
     }
 
+.. _authentication_permissions:
+
+Permissions
+===========
+
+Datasette plugins can check if an actor has permission to perform an action using the :ref:`datasette.permission_allowed(...)<datasette_permission_allowed>` method. This method is also used by Datasette core code itself, which allows plugins to help make decisions on which actions are allowed by implementing the :ref:`permission_allowed(...) <plugin_permission_allowed>` plugin hook.
+
 .. _authentication_permissions_canned_queries:
 
 Permissions for canned queries

docs/internals.rst

@@ -116,6 +116,8 @@ This method lets you read plugin configuration values that were set in ``metadat
 
 Renders a `Jinja template <https://jinja.palletsprojects.com/en/2.11.x/>`__ using Datasette's preconfigured instance of Jinja and returns the resulting string. The template will have access to Datasette's default template functions and any functions that have been made available by other plugins.
 
+.. _datasette_permission_allowed:
+
 await .permission_allowed(actor, action, resource_type=None, resource_identifier=None, default=False)
 -----------------------------------------------------------------------------------------------------