commit b9684ec1de0d1af5bda91e7c074e63187a1ba0dc
parent f46e9166bc5d79fef2c8dc7888c9c84bbb9cc3ad
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Mon, 16 Jun 2025 11:47:48 +0200
Update documentation more for clarity #9646
Diffstat:
1 file changed, 12 insertions(+), 8 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -103,15 +103,19 @@ Currently, the API supports two main authentication methods:
* ``external``: With this method, no checks are done by the merchant backend.
Instead, a reverse proxy / API gateway must do all authentication/authorization checks.
* ``token``: With this method, the client must provide a ``Authorization: Bearer $TOKEN``
- header, where ``$TOKEN`` is a secret authentication token configured for the instance which must begin with the RFC 8959 prefix followed by
- the instances password.
- If the instance password is lost, the administrator can set a token (including the RFC 8959 prefix!) for the default instance using the ``--auth`` command line option,
+ header, where ``$TOKEN`` is a secret authentication token configured for the instance.
+ The format of ``$TOKEN`` is ``secret-token: $INSTANCE_PASSWORD``.
+ If the ``$INSTANCE_PASSWORD`` is lost, the administrator can set a token (including the ``secret-token: `` prefix!)
+ for the default instance using the ``--auth`` command line option of the service,
or by restarting the service by providing an environment variable called ``TALER_MERCHANT_TOKEN``.
- Alternatively, the ``taler-merchant-passwd`` command-line tool may be used to set the password for any instance.
-
-In addition to the password token, clients can send a **login token** which they may obtain from
-the ``/private/token`` endpoint, exchanging it for the password token.
-Such a login token is valid only for a limited period of time and can be used by clients to avoid storing the
+ Alternatively, the ``taler-merchant-passwd`` command-line tool may be used to set or reset the password for any instance
+ by an administrator.
+
+As an alternative to the long-term instance password, clients can send a **login token** as ``$INSTANCE_PASSWORD`` in a
+``$TOKEN``.
+The login token may be obtained from the ``/private/token`` endpoint, which itself requires
+authentication.
+A login token is valid only for a limited period of time and can be used by clients to avoid storing the
long-term login secrets from an authentication method.
-----------------
