From 691baf2f742f27443bbfcca221715580f06d9ede Mon Sep 17 00:00:00 2001
From: Florian Dold <florian@dold.me>
Date: Mon, 1 Mar 2021 11:46:51 +0100
Subject: separate out auth configuration

---
 core/api-merchant.rst | 56 +++++++++++++++++++++++++++++++++------------------
 1 file changed, 36 insertions(+), 20 deletions(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index e2ec56c0..5a9e6bf5 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -826,20 +826,7 @@ Setting up instances
       name: string;
 
       // Authentication settings for this instance
-      auth: {
-        // Type of authentication.
-        // "external":  The mechant backend does not do
-        //   any authentication checks.  Instead an API
-        //   gateway must do the authentication.
-        // "token": The merchant checks an auth token.
-        //   See "token" for details.
-        method: "external" | "token";
-
-        // For method "external", this field is mandatory.
-        // It specifies the "Authentication" HTTP header required to
-        // authorize management to access the instance.
-        token?: string;
-      }
+      auth: InstanceAuthConfigurationMessage;
 
       // The merchant's physical address (to be put into contracts).
       address: Location;
@@ -873,6 +860,35 @@ Setting up instances
     }
 
 
+.. http:post:: /private/instances/$INSTANCE/auth
+
+   Update the authentication settings for an instance.
+
+   **Request** the request must be an `InstanceAuthConfigurationMessage`.
+
+  :http:statuscode:`204 No content`:
+    The backend has successfully created the instance.
+  :http:statuscode:`404 Not found`:
+    This instance is unknown and thus cannot be reconfigured.
+
+  .. ts:def:: InstanceAuthConfigurationMessage
+
+    interface InstanceAuthConfigurationMessage {
+      // Type of authentication.
+      // "external":  The mechant backend does not do
+      //   any authentication checks.  Instead an API
+      //   gateway must do the authentication.
+      // "token": The merchant checks an auth token.
+      //   See "token" for details.
+      method: "external" | "token";
+
+      // For method "external", this field is mandatory.
+      // It specifies the "Authentication" HTTP header required to
+      // authorize management to access the instance.
+      token?: string;
+    }
+
+
 .. http:patch:: /private/instances/$INSTANCE
 
   Update the configuration of a merchant instance.  PATCH operations against
@@ -904,12 +920,6 @@ Setting up instances
       // Merchant name corresponding to this instance.
       name: string;
 
-      // "Authentication" header required to authorize management access the instance.
-      // Optional, if not given authentication will be disabled for
-      // this instance (hopefully authentication checks are still
-      // done by some reverse proxy).
-      auth_token?: string;
-
       // The merchant's physical address (to be put into contracts).
       address: Location;
 
@@ -1039,6 +1049,12 @@ Inspecting instances
       // offers we make be valid by default?
       default_pay_deadline: RelativeTime;
 
+      // Authentication configuration.
+      // Does not contain the token when token auth is configured.
+      auth: {
+        type: "external" | "token";
+      };
+
     }
 
   .. ts:def:: MerchantAccount
-- 
cgit v1.2.3