document /login API for merchant

1 files changed, 53 insertions, 0 deletions

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