commit 6040544c6f1d4769f7fd3880b0ee52aa22c6eecd
parent 8c775a09808ce3d96f365cc23cea10fe0bf96617
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Sun, 6 Jul 2025 15:21:09 +0200
restructure API message auth config
Diffstat:
1 file changed, 27 insertions(+), 19 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -123,11 +123,11 @@ Access tokens can be requested with a (limiting) scope. Available scopes and the
* ``readonly``: ``*-read`` -- Access to APIs using ``GET`` requests is always allowed.
* ``write`` (*deprecated*): See ``all``.
-* ``all``: ``*`` -- General access to all APIs and endpoints. (Since **v19**)
-* ``order-simple``: ``orders-read``, ``orders-write`` -- Allows the creation of orders and checking of payment status. (Since **v19**)
-* ``order-pos``: ``orders-read``, ``orders-write``, ``inventory-lock`` -- Same as ``order-simple`` and allows inventory locking. (Since **v19**)
-* ``order-mgmt``: ``orders-read``, ``orders-write``, ``orders-refund`` -- Same as ``order-simple`` and also allows refunding. (Since **v19**)
-* ``order-full``: ``orders-read``, ``orders-write``, ``inventory-lock``, ``orders-refund`` -- Same ``order-pos`` and ``order-mgmt`` combined. (Since **v19**)
+* ``all``: ``*`` -- General access to all APIs and endpoints. (@since **v19**)
+* ``order-simple``: ``orders-read``, ``orders-write`` -- Allows the creation of orders and checking of payment status. (@since **v19**)
+* ``order-pos``: ``orders-read``, ``orders-write``, ``inventory-lock`` -- Same as ``order-simple`` and allows inventory locking. (@since **v19**)
+* ``order-mgmt``: ``orders-read``, ``orders-write``, ``orders-refund`` -- Same as ``order-simple`` and also allows refunding. (@since **v19**)
+* ``order-full``: ``orders-read``, ``orders-write``, ``inventory-lock``, ``orders-refund`` -- Same ``order-pos`` and ``order-mgmt`` combined. (@since **v19**)
Since **v19** the scope may be suffixed with ``:refreshable``, e.g. ``order-pos:refreshable``.
This allows the token to be refreshed at the token endpoint.
@@ -1170,18 +1170,26 @@ Setting up instances
.. 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 API is accessible through API tokens.
- // Tokens are retrieved from the /private/token
- // endpoint.
- // See "password" for details.
- method: "external" | "token";
-
- // Deprecated: For method "token", this field is mandatory,
+ 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";
+ }
+
+ .. ts:def:: InstanceAuthConfigToken
+
+ 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:".
// After the auth token has been set (with method "token"),
@@ -1189,7 +1197,7 @@ Setting up instances
// header.
token?: string;
- // Since **v19**: For method "token", this field is mandatory.
+ // @since v19: For method "token", 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
@@ -3312,7 +3320,7 @@ Inspecting orders
choice_index?: Integer;
// If the order is paid, set to the last time when a payment
- // was made to pay for this order. Since **v14**.
+ // was made to pay for this order. @since **v14**.
last_payment: Timestamp;
// The wire transfer status from the exchange for this order if
