From 164ad4f4367a23c9cdf77e7f39524ba41d1bf1ee Mon Sep 17 00:00:00 2001
From: MS <ms@taler.net>
Date: Fri, 2 Dec 2022 14:30:58 +0100
Subject: Sandbox API: authentication notes.

---
 libeufin/api-sandbox.rst | 49 ++++++++++++++++++++++++++++++++++++------------
 1 file changed, 37 insertions(+), 12 deletions(-)

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 44938800..530aefe3 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -8,38 +8,47 @@ Sandbox API
 Demobanks.
 ^^^^^^^^^^
 
-Sandbox is designed to allow multiple banks being hosted,
+Sandbox is designed to allow multiple *demobanks* being hosted,
 where every demobank can have its own configuration (including
 a different currency).  A demobank has a name, although currently
 only one demobank, named ``default``, is supported.  Such demobank
-activates the API trunk ``/demobanks/default``, under which other
+activates the API segment ``/demobanks/default``, under which other
 APIs are then served.  Those APIs include Access API, Integration
 API, (part of the) Wire Gateway API (the add-incoming call), and
 :ref:`one call to create EBICS subscribers <demobank-create-ebics-subscriber>`.
 
 Access API.
-^^^^^^^^^^
+^^^^^^^^^^^
 
 Every endpoint is served under ``/demobanks/default/access-api``.
-See :doc:`/core/api-bank-access`.
+See :doc:`/core/api-bank-access`.  This API offers *users management*.
 
 Integration API.
 ^^^^^^^^^^^^^^^^
 
 Every endpoint is served under ``/demobanks/default/integration-api``.
-See :doc:`/core/api-bank-integration`.
+See :doc:`/core/api-bank-integration`.  This API handles the communication
+with Taler wallets.
 
 Taler Wire Gateway API.
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Served under ``/demobanks/default/taler-wire-gateway``.  Currently,
 only the :ref:`admin/add-incoming <twg-admin-add-incoming>` endpoint
-is implemented.  This endpoint allows testing, whereas the rest of
+is implemented.  This endpoint allows testing, but the rest of
 this API does never involve the Sandbox. 
 
+.. note::
+
+  The following endpoints are **not** served under the ``/demobank/default`` segment.
+
 EBICS.
 ^^^^^^
 
+Except of the main EBICS server located at /ebicsweb, all
+the EBICS calls have to authenticate the 'admin' user via
+the HTTP basic auth scheme.
+
 HTTP Service
 ++++++++++++
 
@@ -52,7 +61,7 @@ Hosts.
 
 .. http:post:: /admin/ebics/hosts
 
-   Creates a new Ebics host.
+   Create a new EBICS host.
 
    **Request:**
 
@@ -90,7 +99,6 @@ Hosts.
    meant for tests (as the Sandbox itself is) and no backup will be
    produced along this operation.
 
-
 Subscribers.
 ++++++++++++
 
@@ -119,6 +127,11 @@ Subscribers.
        // bank account label
        label: string;
 
+       // Customer username that owns the bank account.
+       // Currency policy only allows same-named usernames
+       // and bank accounts.
+       owner: string;
+
      }
 
 .. _demobank-create-ebics-subscriber:
@@ -211,9 +224,20 @@ Subscribers.
 Bank accounts.
 ^^^^^^^^^^^^^^
 
+The access to a particular bank account is granted either to the
+owner or to admin, via the HTTP basic auth scheme.  A 'owner' is
+a registered customer, who is identified by a username.  The
+registration of customers is offered via the :doc:`Access API /core/api-bank-access`.
+
+.. note::
+
+   The current version allows only one bank account per
+   customer, where the bank account name (also called 'label')
+   equals the owner's username.
+
 .. http:get:: /admin/bank-accounts
 
-   Give summary of all the bank accounts.
+   Give summary of all the bank accounts.  Only admin allowed.
 
    **Response:**
 
@@ -256,7 +280,8 @@ Bank accounts.
 
 .. http:post:: /admin/bank-accounts/$accountLabel
 
-  create bank account.
+  Create bank account.  Existing users without a bank account
+  can request too.
 
   **Request:** :ts:type:`AdminBankAccount`
 
@@ -331,13 +356,13 @@ JSON.
 .. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions
 
    Generate one incoming and one outgoing transaction for the bank account
-   identified by ``$accountLabel``.
+   identified by ``$accountLabel``.  Only admin allowed.
 
 .. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
 
    Book one incoming transaction for $accountLabel.
    The debtor (not required to be in the same bank)
-   information is taken from the request.
+   information is taken from the request.  Only admin allowed.
 
    **Request:**
    
-- 
cgit v1.2.3