merchant backend: change auth API to make it harder to shoot yourself in the foot

1 files changed, 15 insertions, 5 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 1f96ae62..e2ec56c0 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -825,11 +825,21 @@ 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;
+      // 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;
+      }
 
       // The merchant's physical address (to be put into contracts).
       address: Location;