diff --git a/source/development/api.rst b/source/development/api.rst
index e762bf57..96b61e84 100644
--- a/source/development/api.rst
+++ b/source/development/api.rst
@@ -29,6 +29,13 @@ The $key and $secret parameters are used to pass the API credentials using curl.
When using Postman to test an API call, use the 'basic auth' authorization type. The $key and $secret parameters go into Username/Password respectively.
+.. note::
+
+ Always make sure the owner of the key is authorized to access the resource in question, the "Effective Privileges" set on the user
+ shows which resources are accessible. (Edit reveals the endpoints assigned to each resource).
+
+ ACL's are explained in :doc:`development/components/acl `).
+
Core API
--------
diff --git a/source/development/components/acl.rst b/source/development/components/acl.rst
index d6fce3dc..ecc03f54 100644
--- a/source/development/components/acl.rst
+++ b/source/development/components/acl.rst
@@ -10,23 +10,43 @@ Access Control List
Overview
--------
-The current ACL system is targeted at delivering backwards compatibility
-for legacy code and being able to extend this a little to add new
+The ACL system is targeted at delivering backwards compatibility
+for legacy code and being able to extend this to add new
features without having to reimplement the whole system.
-In the legacy system the access control is using the following steps to
-determine if a page can be accessed by a user:
+The following steps determine if a page can be accessed by a user:
-#. The user, stored in the config.xml file at system/user (one item per
- user)
-#. One or more groups for that user, stored in system/group which
- contains priv sections.
-#. A PHP file binding the priv section content to a page mask (including
- wildcards)
+#. The user, stored in the config.xml file at system/user may set "Effective Privileges" valid for that explicit entry, stored in sections
+#. One or more groups for that user, stored in system/group which contains priv sections as well.
+#. An XML file (:code:`ACL.xml`) linking logical acl keys to uri patterns
+
+Access controls for most legacy components are stored in models/OPNsense/Core/ACL/ACL.xml, most new components add their own
+ACL's in the model belonging to the component. All stored :code:`ACL.xml` files combined determine the full set of options available
+in the user/group manager. There is no expicit requirement which model services which ACL.
+
+.. Note::
+
+ When in need of a single ACL to match an explicit set of components (pages/api endpoints), one can add an ACL file easily
+ for a module without further logic.
+
+---------------
+ACL format
+---------------
+
+Each ACL file is stored in the model location (/usr/local/opnsense/mvc/app/models/) where :code:`ACL.xml` files
+are stored in the location [VENDOR]/[MODULE]/ACL/ACL.xml. The format of the file is as follows:
+
+.. code-block:: html
+
+
+ <---- as stored for the user/group
+ My ACL name <---- name visible in the user manager
+
+ path/to/my/module <--- list of uri's this ACL should unlock.
+
+
+
-Our temporary solution is to keep the user and the group in place and replace the
-PHP file with a simple config in the model which uses the same mask construction
-there was in the old codebase. To bind priv to pages, edit models/OPNsense/Core/ACL\_Legacy\_Page\_Map.txt
--------------
Usage from PHP