taler-docs

commit 47a86dfcb9af85ee38f4374eb49d2ab47d348e34
parent ced82b398c7ce1053f0de27d5e5299970068e3b6
Author: Christian Grothoff <grothoff@gnunet.org>
Date:   Tue,  5 Sep 2023 18:04:48 +0200

document /login API for merchant

Diffstat:
M
core/api-libeufin-bank.rst
 | 
2
+-
M
core/api-merchant.rst
 | 
53
+++++++++++++++++++++++++++++++++++++++++++++++++++++

2 files changed, 54 insertions(+), 1 deletion(-)
diff --git a/core/api-libeufin-bank.rst b/core/api-libeufin-bank.rst
@@ -73,7 +73,7 @@ client to authenticate as the admin.
 
    **Parameters**
 
-   .. ts:def:: LoginRquest
+   .. ts:def:: LoginRequest
 
      interface LoginRequest {
        scope: "readonly" | "write";
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -1011,6 +1011,59 @@ Setting up instances
 
 .. http:post:: [/instances/$INSTANCE]/private/login
 
+   **Request:**
+
+   The request must be a `LoginRequest`.
+
+   **Response:**
+
+  :http:statuscode:`200 Ok`:
+    The backend is returning the access token in a
+    `LoginSuccessResponse`.
+
+   **Details:**
+
+   .. note::
+
+     Typically the ``access_token`` would be an EdDSA signature
+     over (username, scope, timestamp, expiry).
+
+     Alternatively, valid access tokens could also be random identifiers
+     stored in a database table.
+
+   .. ts:def:: LoginRequest
+
+     interface LoginRequest {
+       // Scope of the token (which kinds of operations it will allow)
+       scope: "readonly" | "write";
+
+       // Server may impose its own upper bound
+       // on the token validity duration
+       duration?: RelativeTime;
+
+       // Can this token be refreshed?
+       // Defaults to false.
+       refreshable?: boolean;
+     }
+
+   .. ts:def:: LoginSuccessResponse
+
+     interface LoginSuccessResponse {
+       // The bearer token that can be used to access resources
+       // that are in scope for some time.
+       access_token: string;
+
+       // Scope of the token (which kinds of operations it will allow)
+       scope: "readonly" | "write";
+
+       // Server may impose its own upper bound
+       // on the token validity duration
+       expiration: Timestamp;
+
+       // Can this token be refreshed?
+       refreshable: boolean;
+     }
+
 
 .. http:patch:: /management/instances/$INSTANCE
 .. http:patch:: [/instances/$INSTANCE]/private