taler-docs

commit 3173469f662a8a82b9bc5ce01157630404eb4db1
parent 694a5074b0a4005086513175e10226f29d570151
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Sun,  6 Jul 2025 16:15:13 +0200

deprecate external auth

Diffstat:
M
core/api-merchant.rst
 | 
52
++++++++++++++++++++++++++++++----------------------

1 file changed, 30 insertions(+), 22 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -97,9 +97,9 @@ of that instance.
 
 Currently, the ``/private/auth/`` API supports two main authentication methods in the ``InstanceAuthConfigurationMessage``:
 
-* ``external``:  With this method, no checks are done by the merchant backend.
+* ``external``: (*@deprecated since vNOEXTAUTH*) With this method, no checks are done by the merchant backend.
   Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
-* ``token`` (**v19**): With this method, the client must provide a ``Authorization: Bearer $TOKEN``
+* ``token`` (**@since v19**): With this method, the client must provide a ``Authorization: Bearer $TOKEN``
   header when accessing a protected endpoint, where ``$TOKEN`` is an authentication token
   retrieved from the ``/private/token`` endpoint using basic authorization.
   A login token is valid only for a limited period of time and can be used by clients to avoid storing the
@@ -110,7 +110,7 @@ Currently, the ``/private/auth/`` API supports two main authentication methods i
   using the ``taler-merchant-passwd`` command-line tool.
   Any API may also be accessed using the bearer authentication ``secret-token: $INSTANCE_PASSWORD``.
   Notice that this behaviour is deprecated and will be phased out in favor of login tokens.
-* ``token`` (*deprecated*): With this method, the client must provide an authentication token in
+* ``token`` (*@deprecated since v19*): With this method, the client must provide an authentication token in
   the format ``secret-token: $INSTANCE_PASSWORD``.
   The behaviour is then equivalent to the ``token`` method above.
   Any API may be accessed using the bearer authentication ``secret-token: $INSTANCE_PASSWORD``.
@@ -1170,34 +1170,17 @@ Setting up instances
 
   .. ts:def:: InstanceAuthConfigurationMessage
 
-    type InstanceAuthConfigurationMessage = AuthConfigExternal | AuthConfigToken;
-
-  .. ts:def:: InstanceAuthConfigExternal
-
-    interface InstanceAuthConfigExternal {
-      // The mechant backend does not do
-      // any authentication checks.  Instead an API
-      // gateway must do the authentication.
-      method: "external";
-    }
+    type InstanceAuthConfigurationMessage = InstanceAuthConfigToken | InstanceAuthConfigOLD | InstanceAuthConfigExternal
 
   .. ts:def:: InstanceAuthConfigToken
 
+    // @since v19
     interface InstanceAuthConfigToken {
       // The API is accessible through API tokens.
       // Tokens are retrieved from the /private/token
       // endpoint.
       method: "token";
 
-      // @deprecated v19: For method "token", this field is mandatory,
-      // unless the new "password" field is used.
-      // The value of this field MUST begin with the string "secret-token:".
-      // The backend behaviour is the same as if the "password" field were
-      // used without the "secret-token:" prefix.
-      token?: string;
-
-      // @since v19: For method "token", this field is mandatory,
-      // unless the deprecated "token" field is used.
       // Authentication against the /private/token endpoint
       // is done using basic authentication with the configured password
       // in the "password" field. Tokens are passed to other endpoints for
@@ -1206,6 +1189,31 @@ Setting up instances
 
     }
 
+  // @deprecated v19
+  .. ts:def:: InstanceAuthConfigTokenOLD
+
+    interface InstanceAuthConfigToken {
+      // The API is accessible through API tokens.
+      // Tokens are retrieved from the /private/token
+      // endpoint.
+      method: "token";
+
+      // The value of this field MUST begin with the string "secret-token:".
+      token?: string;
+
+    }
+
+  // @deprecated vNOEXTAUTH
+  .. ts:def:: InstanceAuthConfigExternal
+
+    interface InstanceAuthConfigExternal {
+      // The mechant backend does not do
+      // any authentication checks.  Instead an API
+      // gateway must do the authentication.
+      method: "external";
+    }
+
+
 .. http:post:: [/instances/$INSTANCE]/private/token
 
   Retrieve an access token for the merchant API for instance