commit aea989cc961d009c914258ab750a4eb639c354bd
parent 21c409b2da9eec003a1261d94a5c7e044461ea8d
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Tue, 17 Jun 2025 16:33:07 +0200
add v42 deprecations
Diffstat:
1 file changed, 36 insertions(+), 19 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -98,25 +98,29 @@ Authentication
Each merchant instance has separate authentication settings for the private API resources
of that instance.
-Currently, the API supports two main authentication methods:
+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.
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.
- 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!)
+* ``password`` (**v42**): 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
+ long-term login secrets from an authentication method.
+ The username corresponds to the instance ``$ID``, the password to the instance password ``$INSTANCE_PASSWORD``.
+ The token must be provided as a bearer token with the RFC 8958 prefix (``secret-token``) in the authorization header.
+ If the ``$INSTANCE_PASSWORD`` is lost, the administrator can set a password
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``.
+ or by restarting the service by providing an environment variable called ``TALER_MERCHANT_PASSWORD``.
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.
+ 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
+ the format ``secret-token: $INSTANCE_PASSWORD``.
+ The behaviour is then equivalent to the ``password`` method above.
+ Any API may 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.
Scopes
^^^^^^
@@ -1171,9 +1175,12 @@ Setting up instances
// "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.
+ // "token": (deprecated) The merchant checks an auth token.
// See "token" for details.
- method: "external" | "token";
+ // "password": APIs use login tokens retrieved from the /private/token
+ // endpoint.
+ // See "password" for details.
+ method: "external" | "token" | "password";
// For method "token", this field is mandatory.
// The token MUST begin with the string "secret-token:".
@@ -1182,6 +1189,13 @@ Setting up instances
// header.
token?: string;
+ // For method "password", this field is mandatory.
+ // 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
+ // authorization using RFC 8959 bearer tokens.
+ password?: string;
+
}
.. http:post:: [/instances/$INSTANCE]/private/token
@@ -1202,28 +1216,31 @@ Setting up instances
interface LoginTokenRequest {
// Scope of the token (which kinds of operations it will allow)
- scope: "readonly" | "write";
+ scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
// Server may impose its own upper bound
// on the token validity duration
duration?: RelativeTime;
// Can this token be refreshed?
- // Defaults to false. DEPRECATED since v42
+ // Defaults to false. Deprecated since v42. Use ":refreshable" scope prefix instead.
refreshable?: boolean;
}
.. ts:def:: LoginTokenSuccessResponse
interface LoginTokenSuccessResponse {
+ // deprecated. See access_token
+ token: string;
+
// The login token that can be used to access resources
// that are in scope for some time. Must be prefixed
// with "Bearer " when used in the "Authorization" HTTP header.
// Will already begin with the RFC 8959 prefix.
- token: string;
+ access_token: string;
// Scope of the token (which kinds of operations it will allow)
- scope: "readonly" | "write";
+ scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full";
// Server may impose its own upper bound
// on the token validity duration
