[taler-docs] 02/02: document /login API for merchant

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

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

    document /login API for merchant
---
 core/api-libeufin-bank.rst |  2 +-
 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
index ad6bb1b0..f7b1a7e9 100644
--- 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
index 71f33b0e..bec280a1 100644
--- 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

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.