taler-docs

commit d2678f76a06d73292777d94831741963d2bd6914
parent 0964251471216b8b256247d7abb453734d420f94
Author: Florian Dold <dold@taler.net>
Date:   Sun, 30 Aug 2026 00:21:27 +0200

exchange AML API: document officer access query

Diffstat:
M
core/api-exchange.rst
 | 
8
++++++--
A
core/exchange/get-aml-OFFICER_PUB.rst
 | 
47
+++++++++++++++++++++++++++++++++++++++++++++++

2 files changed, 53 insertions(+), 2 deletions(-)
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -30,11 +30,11 @@ defines all specific terms used in this section.
 Version History
 ---------------
 
-The currently implemented protocol version is **v39**.
+The currently implemented protocol version is **v40**.
 
 * Wallet-core is currently targeting **vXX**.
 * The merchant is currently targeting **v34**.
-* The AML SPA is currently targeting **v31**.
+* The AML SPA is currently targeting **v40**.
 * The KYC SPA is currently targeting **v30**.
 
 **Version history:**
@@ -52,6 +52,8 @@ The currently implemented protocol version is **v39**.
 * ``v38``: adds ``build_version`` to :http:get:`/config </config>`
 * ``v39``: adds ``exchange_payto_uri`` to
            :http:get:`/transfers/$WTID </transfers/$WTID>`
+* ``v40``: adds :http:get:`/aml/$OFFICER_PUB </aml/$OFFICER_PUB>` to report
+           the authenticated AML officer's name and access level
 
 **Upcoming versions:**
 
@@ -555,6 +557,8 @@ This API is only for designated AML officers. It is used
 to allow exchange staff to monitor suspicious transactions
 and freeze or unfreeze accounts suspected of money laundering.
 
+.. include:: exchange/get-aml-OFFICER_PUB.rst
+
 .. include:: exchange/get-aml-OFFICER_PUB-measures.rst
 
 .. include:: exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.rst
diff --git a/core/exchange/get-aml-OFFICER_PUB.rst b/core/exchange/get-aml-OFFICER_PUB.rst
@@ -0,0 +1,47 @@
+.. http:get:: /aml/$OFFICER_PUB
+
+  Return information about the authenticated AML officer.  This endpoint is
+  used by AML staff applications to verify enrollment and determine whether
+  write operations are permitted.
+
+  This endpoint was introduced in protocol **v40**.
+
+  **Request:**
+
+  *Taler-AML-Officer-Signature*:
+    The client must provide a Base-32 encoded EdDSA signature made with
+    ``$OFFICER_PRIV`` that affirms the desire to obtain AML data.  As with the
+    other AML GET endpoints, this is an authentication signature and does not
+    bind the details of the request.
+
+  **Response:**
+
+  :http:statuscode:`200 Ok`:
+    The AML officer is active.  The response contains an
+    `AmlOfficerInfo` object.
+  :http:statuscode:`400 Bad Request`:
+    The public key is malformed or the required signature header is missing or
+    malformed.
+  :http:statuscode:`403 Forbidden`:
+    The signature is invalid, or the AML officer is unknown or inactive.
+    Invalid signatures use
+    ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_GET_SIGNATURE_INVALID``; unknown
+    or inactive officers use
+    ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``.
+  :http:statuscode:`500 Internal server error`:
+    The exchange failed to read the AML officer record from its database.
+
+  **Details:**
+
+  .. ts:def:: AmlOfficerInfo
+
+    interface AmlOfficerInfo {
+
+      // Legal name configured for this AML officer.
+      officer_name: string;
+
+      // True if the officer may read AML data but may not submit AML
+      // decisions. False grants both read and write access.
+      read_only: boolean;
+
+    }