commit 6a4e1cc9196799b241bc9a231593472a495e17cc parent e96fabe668b4a46363672f0ae031373df317e004 Author: Christian Grothoff <christian@grothoff.org> Date: Wed, 5 Aug 2026 15:12:57 +0200 fix #11574 Diffstat:
94 files changed, 332 insertions(+), 108 deletions(-)
diff --git a/core/api-merchant.rst b/core/api-merchant.rst @@ -223,23 +223,236 @@ Currently, the ``/private/auth/`` API supports two main authentication methods i For testing, the service may be started with the configuration option ``DISABLED_AUTHENTICATION = YES`` in section ``[merchant]`` (@since **v20**). -Scopes -^^^^^^ +.. _merchant-api-scopes: + +Scopes and permissions +^^^^^^^^^^^^^^^^^^^^^^ + +Authorization in the merchant backend is expressed with *permissions*. Every +endpoint that requires authorization requires exactly one permission, which is +stated as **Required permission** in the documentation of that endpoint. +Permission names have the form ``$RESOURCE-$ACTION``, where ``$ACTION`` is +usually ``read`` (for operations that only inspect state) or ``write`` (for +operations that change it). -Access tokens can be requested with a (limiting) scope. Available scopes and their associated permissions are: +Clients do not request individual permissions. Instead, an access token is +issued for a *scope*, which is a fixed, named set of permissions. A request is +authorized if the permission required by the endpoint is covered by the scope +of the access token that was used. -* ``readonly``: ``*-read`` -- Access to APIs using ``GET`` requests is always allowed. -* ``write`` (*deprecated*): See ``all``. -* ``all``: ``*`` -- General access to all APIs and endpoints and always refreshable. (@since **v19**) -* ``spa``: ``*`` -- General access to all APIs and endpoints. (@since **v20**) -* ``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**) +Permissions +""""""""""" + +The following permissions exist: + +.. list-table:: + :widths: 25 75 + :header-rows: 1 + + * - Permission + - Grants access to + * - ``accounts-read`` + - Listing and inspecting the bank accounts of the instance, and starting + KYC authentication for one of them. + * - ``accounts-write`` + - Adding, modifying and deleting bank accounts of the instance, and + accepting the terms of service of an exchange ahead of time. + * - ``auth-write`` + - Changing the authentication settings of the instance itself + (via the instance's own ``/private/auth`` endpoint). + * - ``categories-read`` + - Listing and inspecting product categories. + * - ``categories-write`` + - Creating, modifying and deleting product categories. + * - ``donau-read`` + - Listing the linked Donau charity instances. + * - ``donau-write`` + - Adding and removing Donau charity instance links. + * - ``fountains-read`` + - Listing and inspecting token fountains. Since **vTokenFountains**. + * - ``fountains-write`` + - Creating, modifying and deleting token fountains. + Since **vTokenFountains**. + * - ``groups-read`` + - Listing product groups. + * - ``groups-write`` + - Creating, modifying and deleting product groups. + * - ``instances-auth-write`` + - Changing the authentication settings of *any* instance via the + ``/management/`` API. Only the ``admin`` instance can hold this + permission in a useful way. + * - ``instances-kyc-read`` + - Querying the KYC status of *any* instance via the ``/management/`` API. + * - ``instances-read`` + - Reading the configuration of the instance itself. + * - ``instances-write`` + - Creating, inspecting, modifying and deleting instances. Note that this + permission is required for *all* operations on the ``/management/`` + instance API, including the ``GET`` operations that merely list or + inspect instances, as well as for modifying or deleting the instance + itself via its own private API. + * - ``kyc-read`` + - Querying the KYC status of the instance itself. + * - ``orders-read`` + - Listing orders and checking their payment, refund and wire transfer + status. + * - ``orders-write`` + - Creating orders, forgetting parts of a contract, collecting zero-amount + orders and deleting orders. + * - ``orders-refund`` + - Granting refunds and recording externally settled refunds. + * - ``otp-devices-read`` + - Listing and inspecting one-time-password (OTP) devices. + * - ``otp-devices-write`` + - Creating, modifying and deleting OTP devices. + * - ``pos-read`` + - Downloading the full point-of-sale configuration + (:http:get:`[/instances/$INSTANCE]/private/pos`). + * - ``pots-read`` + - Listing and inspecting money pots. + * - ``pots-write`` + - Creating, modifying and deleting money pots. + * - ``products-read`` + - Listing and inspecting products in the inventory. + * - ``products-write`` + - Adding, modifying and deleting products in the inventory. + * - ``products-lock`` + - Locking products in the inventory + (:http:post:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock`). + * - ``reports-read`` + - Listing and inspecting reports. + * - ``reports-write`` + - Creating, modifying and deleting reports. + * - ``statistics-read`` + - Reading counter, amount and transaction statistics. + * - ``templates-read`` + - Listing and inspecting order templates. + * - ``templates-write`` + - Creating, modifying and deleting order templates. + * - ``tokenfamilies-read`` + - Listing and inspecting token families. + * - ``tokenfamilies-write`` + - Creating, modifying and deleting token families. + * - ``tokens-read`` + - Listing the access tokens that were issued for the instance. + * - ``tokens-write`` + - Revoking access tokens of the instance by serial. + * - ``token-refresh`` + - Obtaining a new access token from + :http:post:`[/instances/$INSTANCE]/private/token` using an existing + access token. This permission is special: it is *not* part of any + scope's permission set and is not implied by ``*``. It is granted + exactly if the access token used is refreshable (see below). + * - ``transfers-read`` + - Listing expected and actual wire transfers, including incoming + transfers. + * - ``transfers-write`` + - Informing the backend about wire transfers and deleting such records. + * - ``units-read`` + - Listing and inspecting measurement units. + * - ``units-write`` + - Creating, modifying and deleting measurement units. + * - ``webhooks-read`` + - Listing and inspecting webhooks. + * - ``webhooks-write`` + - Creating, modifying and deleting webhooks. + +Endpoints of the wallet-facing (public) API, such as those used to claim, pay +for or abort an order, require no permission at all and are documented as +"**Required permission:** none". -Since **v19** the scope may be suffixed with ``:refreshable``, e.g. ``order-pos:refreshable``. +Scopes +"""""" + +Access tokens can be requested with a (limiting) scope. The available scopes +and the permissions they grant are: + +.. list-table:: + :widths: 15 45 40 + :header-rows: 1 + + * - Scope + - Permissions + - Remarks + * - ``readonly`` + - ``*-read`` + - Every permission ending in ``-read``. Note that this does *not* include + the ``/management/`` instance API, which requires ``instances-write`` + even for ``GET`` requests. + * - ``all`` + - ``*`` + - Every permission. Tokens with this scope are always refreshable. + @since **v19** + * - ``write`` + - ``*`` + - @deprecated since **v19**, identical to ``all``. + * - ``spa`` + - ``*`` + - Every permission; used by the merchant backoffice SPA. Unlike ``all``, + this scope is not implicitly refreshable. @since **v20** + * - ``order-simple`` + - ``orders-read``, ``orders-write`` + - Allows the creation of orders and checking of payment status. + @since **v19** + * - ``order-pos`` + - ``orders-read``, ``orders-write``, ``pos-read``, ``products-lock`` + - Same as ``order-simple``, plus reading the point-of-sale configuration + and inventory locking. @since **v19** + * - ``order-mgmt`` + - ``orders-read``, ``orders-write``, ``pos-read``, ``orders-refund`` + - Same as ``order-simple``, plus reading the point-of-sale configuration + and granting refunds. @since **v19** + * - ``order-full`` + - ``orders-read``, ``orders-write``, ``pos-read``, ``products-lock``, + ``orders-refund`` + - ``order-pos`` and ``order-mgmt`` combined. @since **v19** + +.. note:: + + The ``products-lock`` permission granted by ``order-pos`` and ``order-full`` + is only required for explicitly locking products via + :http:post:`[/instances/$INSTANCE]/private/products/$PRODUCT_ID/lock`. + Creating an order (which locks inventory as a side effect) requires only + ``orders-write``. + +.. ts:def:: TokenScope + + // Scope of an access token. Since **v19**, the scope may be + // suffixed with ":refreshable" (see below), for example + // "order-pos:refreshable". "write" is deprecated since **v19** + // and is equivalent to "all". + type TokenScope = "readonly" | "all" | "spa" | "order-simple" | "order-pos" | "order-mgmt" | "order-full" | "write"; + +Matching rules +"""""""""""""" + +Given the permission ``$P`` required by an endpoint and the permission set of +the scope of the access token used, access is granted if any of the following +holds: + +* the scope contains ``*``; +* the scope contains ``*-read`` and ``$P`` ends in ``-read``; +* the scope contains ``*-write`` and ``$P`` ends in ``-write``; +* the scope contains ``$P`` literally. + +The permission ``token-refresh`` is handled separately and is granted if and +only if the access token is refreshable, regardless of the scope's permission +set. + +Refreshable tokens +"""""""""""""""""" + +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. This behaviour replaces the deprecated ``refreshable`` field in the `LoginTokenRequest`. +Tokens with the ``all`` (or the deprecated ``write``) scope are always +refreshable. + +When requesting a token from +:http:post:`[/instances/$INSTANCE]/private/token` with an existing access +token, the requested scope must be a subset of the scope of the token used, +and a non-refreshable token can never be used to obtain a refreshable one. ----------------- Configuration API @@ -1091,6 +1304,9 @@ Permissions * ``donau-read`` — list linked charities. * ``donau-write`` — add or remove charity links. +See :ref:`Scopes <merchant-api-scopes>` for how permissions relate to the +scope of an access token. + Listing charity instances ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/core/merchant/delete-management-instances-INSTANCE.rst b/core/merchant/delete-management-instances-INSTANCE.rst @@ -11,7 +11,7 @@ the instance that is being deleted or the ``admin`` instance, depending on the access path used. - **Required permission:** ``instances-write`` + **Required permission:** ``instances-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/delete-private-accounts-H_WIRE.rst b/core/merchant/delete-private-accounts-H_WIRE.rst @@ -1,6 +1,6 @@ .. http:delete:: [/instances/$INSTANCE]/private/accounts/$H_WIRE - **Required permission:** ``accounts-write`` + **Required permission:** ``accounts-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-categories-CATEGORY_ID.rst b/core/merchant/delete-private-categories-CATEGORY_ID.rst @@ -3,7 +3,7 @@ This is used to delete a category. Since API version **v16**. - **Required permission:** ``categories-write`` + **Required permission:** ``categories-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-donau-DONAU_SERIAL.rst b/core/merchant/delete-private-donau-DONAU_SERIAL.rst @@ -2,7 +2,7 @@ Unlink the Donau charity instance identified by ``$DONAU_SERIAL``. - **Required permission:** ``donau-write`` + **Required permission:** ``donau-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-fountains-FOUNTAIN_ID.rst b/core/merchant/delete-private-fountains-FOUNTAIN_ID.rst @@ -6,7 +6,7 @@ their issue key expires. This endpoint is available since protocol **vTokenFountains**. - **Required permission:** ``fountains-write`` + **Required permission:** ``fountains-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-groups-GROUP_ID.rst b/core/merchant/delete-private-groups-GROUP_ID.rst @@ -2,7 +2,7 @@ This is used to delete information about a group. - **Required permission:** ``groups-write`` + **Required permission:** ``groups-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-orders-ORDER_ID.rst b/core/merchant/delete-private-orders-ORDER_ID.rst @@ -9,6 +9,8 @@ passing ``force``, as such an order may have received payments outside of Taler that the merchant should resolve manually first. + **Required permission:** ``orders-write`` (see :ref:`Scopes <merchant-api-scopes>`) + **Request:** :query force: *Optional*. If set to YES, the order will be deleted diff --git a/core/merchant/delete-private-otp-devices-DEVICE_ID.rst b/core/merchant/delete-private-otp-devices-DEVICE_ID.rst @@ -1,6 +1,6 @@ .. http:delete:: [/instances/$INSTANCE]/private/otp-devices/$DEVICE_ID - **Required permission:** ``otp-devices-write`` + **Required permission:** ``otp-devices-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-pots-POT_ID.rst b/core/merchant/delete-private-pots-POT_ID.rst @@ -5,7 +5,7 @@ there will be no indication that the pot is still in used from the backend. - **Required permission:** ``pots-write`` + **Required permission:** ``pots-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-products-PRODUCT_ID.rst b/core/merchant/delete-private-products-PRODUCT_ID.rst @@ -8,7 +8,7 @@ may disrupt customer flows that depend on those locks (such as pending shopping carts), so it should be used with care. - **Required permission:** ``products-write`` + **Required permission:** ``products-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/delete-private-reports-REPORT_ID.rst b/core/merchant/delete-private-reports-REPORT_ID.rst @@ -2,7 +2,7 @@ This is used to delete report generation from the schedule. - **Required permission:** ``reports-write`` + **Required permission:** ``reports-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-templates-TEMPLATE_ID.rst b/core/merchant/delete-private-templates-TEMPLATE_ID.rst @@ -2,7 +2,7 @@ This is used to delete information about a template. If we no longer use it. - **Required permission:** ``templates-write`` + **Required permission:** ``templates-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-token.rst b/core/merchant/delete-private-token.rst @@ -2,6 +2,9 @@ Delete the token presented in the authorization header. + **Required permission:** none; any client may revoke the access token it + presents. + **Response:** :http:statuscode:`204 No content`: diff --git a/core/merchant/delete-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst b/core/merchant/delete-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst @@ -3,7 +3,7 @@ This is used to delete a token family. Issued tokens of this family will not be spendable anymore. - **Required permission:** ``tokenfamilies-write`` + **Required permission:** ``tokenfamilies-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-tokens-SERIAL.rst b/core/merchant/delete-private-tokens-SERIAL.rst @@ -5,7 +5,7 @@ @since **v19** - **Required permission**: ``tokens-write`` + **Required permission:** ``tokens-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-transfers-TID.rst b/core/merchant/delete-private-transfers-TID.rst @@ -3,7 +3,7 @@ Here, the TID is the 'transfer_serial_id' of the transfer to delete. - **Required permission:** ``transfers-write`` + **Required permission:** ``transfers-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-units-UNIT.rst b/core/merchant/delete-private-units-UNIT.rst @@ -2,7 +2,7 @@ Remove a custom unit from an instance. - **Required permission:** ``units-write`` + **Required permission:** ``units-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/delete-private-webhooks-WEBHOOK_ID.rst b/core/merchant/delete-private-webhooks-WEBHOOK_ID.rst @@ -2,7 +2,7 @@ This is used to delete information about a webhook. - **Required permission:** ``webhooks-write`` + **Required permission:** ``webhooks-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-management-instances-INSTANCE.rst b/core/merchant/get-management-instances-INSTANCE.rst @@ -9,7 +9,8 @@ This endpoint may be used even when mandatory TAN channels were not validated yet. - **Required permission:** ``instances-read`` + **Required permission:** ``instances-read`` on the ``/private`` path, + ``instances-write`` on the ``/management/`` path (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-management-instances.rst b/core/merchant/get-management-instances.rst @@ -3,7 +3,7 @@ This is used to return the list of all the merchant instances. It is only available for the implicit ``admin`` instance. - **Required permission:** ``instances-read`` + **Required permission:** ``instances-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-accounts-H_WIRE.rst b/core/merchant/get-private-accounts-H_WIRE.rst @@ -7,7 +7,7 @@ In this case, an plaintext response suitable for human consumption is returned. - **Required permission:** ``accounts-read`` + **Required permission:** ``accounts-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-accounts.rst b/core/merchant/get-private-accounts.rst @@ -3,7 +3,7 @@ This is used to return the list of all the bank accounts of an instance. - **Required permission:** ``accounts-read`` + **Required permission:** ``accounts-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-categories-CATEGORY_ID.rst b/core/merchant/get-private-categories-CATEGORY_ID.rst @@ -4,7 +4,7 @@ category. Since API version **v16**. - **Required permission:** ``categories-read`` + **Required permission:** ``categories-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-categories.rst b/core/merchant/get-private-categories.rst @@ -4,7 +4,7 @@ and the number of products in each category. Since API version **v16**. - **Required permission:** ``categories-read`` + **Required permission:** ``categories-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-donau.rst b/core/merchant/get-private-donau.rst @@ -2,7 +2,7 @@ Return all Donau charity instances currently linked to ``$INSTANCE``. - **Required permission:** ``donau-read`` + **Required permission:** ``donau-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-fountains-FOUNTAIN_ID.rst b/core/merchant/get-private-fountains-FOUNTAIN_ID.rst @@ -4,7 +4,7 @@ The fountain secret is never returned. This endpoint is available since protocol **vTokenFountains**. - **Required permission:** ``fountains-read`` + **Required permission:** ``fountains-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-fountains.rst b/core/merchant/get-private-fountains.rst @@ -3,7 +3,7 @@ Lists all fountains of the instance. This endpoint is available since protocol **vTokenFountains**. - **Required permission:** ``fountains-read`` + **Required permission:** ``fountains-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-groups.rst b/core/merchant/get-private-groups.rst @@ -3,7 +3,7 @@ This is used to return all the groups that are present in our backend. - **Required permission:** ``groups-read`` + **Required permission:** ``groups-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-incoming-ID.rst b/core/merchant/get-private-incoming-ID.rst @@ -5,7 +5,7 @@ from `ExpectedTransferEntry`. Since protocol **v26**. - **Required permission:** ``transfers-read`` + **Required permission:** ``transfers-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-incoming.rst b/core/merchant/get-private-incoming.rst @@ -4,7 +4,7 @@ anticipating. Since protocol **v20**. - **Required permission:** ``transfers-read`` + **Required permission:** ``transfers-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-kyc.rst b/core/merchant/get-private-kyc.rst @@ -6,7 +6,8 @@ as to the KYC status of the respective account and returns the result. - **Required permission:** ``instances-kyc-read`` + **Required permission:** ``kyc-read`` on the ``/private`` path, + ``instances-kyc-read`` on the ``/management/`` path (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-orders-ORDER_ID.rst b/core/merchant/get-private-orders-ORDER_ID.rst @@ -7,7 +7,7 @@ the contract hash to authenticate, while for this API we assume that the merchant is authenticated (as the endpoint is not ``public``). - **Required permission:** ``orders-read`` + **Required permission:** ``orders-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-orders.rst b/core/merchant/get-private-orders.rst @@ -2,7 +2,7 @@ Returns known orders up to some point in the past. - **Required permission:** ``orders-read`` + **Required permission:** ``orders-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-otp-devices-DEVICE_ID.rst b/core/merchant/get-private-otp-devices-DEVICE_ID.rst @@ -9,7 +9,7 @@ provides inadequate query parameters, the ``otp_code`` is simply omitted from the response. - **Required permission:** ``otp-devices-read`` + **Required permission:** ``otp-devices-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Query:** diff --git a/core/merchant/get-private-otp-devices.rst b/core/merchant/get-private-otp-devices.rst @@ -2,7 +2,7 @@ This is used to return the list of all the OTP devices. - **Required permission:** ``otp-devices-read`` + **Required permission:** ``otp-devices-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-pos.rst b/core/merchant/get-private-pos.rst @@ -4,7 +4,7 @@ Endpoint was introduced in protocol **v15**. - **Required permission:** ``products-read`` + **Required permission:** ``pos-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-pots-POT_ID.rst b/core/merchant/get-private-pots-POT_ID.rst @@ -2,7 +2,7 @@ This is used to obtain detailed information about specific pot. - **Required permission:** ``pots-read`` + **Required permission:** ``pots-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-pots.rst b/core/merchant/get-private-pots.rst @@ -3,7 +3,7 @@ This is used to return all the pots that are present in our backend. - **Required permission:** ``pots-read`` + **Required permission:** ``pots-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-products-PRODUCT_ID.rst b/core/merchant/get-private-products-PRODUCT_ID.rst @@ -2,7 +2,7 @@ This is used to obtain detailed information about a product in the inventory. - **Required permission:** ``products-read`` + **Required permission:** ``products-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-products.rst b/core/merchant/get-private-products.rst @@ -2,7 +2,7 @@ This is used to return the list of all items in the inventory. - **Required permission:** ``products-read`` + **Required permission:** ``products-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-reports-REPORT_ID.rst b/core/merchant/get-private-reports-REPORT_ID.rst @@ -3,7 +3,7 @@ This is used to obtain detailed information about a specific scheduled report. - **Required permission:** ``reports-read`` + **Required permission:** ``reports-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-reports.rst b/core/merchant/get-private-reports.rst @@ -3,7 +3,7 @@ This is used to return all the scheduled reports that are present in our backend. - **Required permission:** ``reports-read`` + **Required permission:** ``reports-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-statistics-amount-SLUG.rst b/core/merchant/get-private-statistics-amount-SLUG.rst @@ -6,7 +6,7 @@ SLUG will be returned. Since protocol **v25**. - **Required permission:** ``statistics-read`` + **Required permission:** ``statistics-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-statistics-counter-SLUG.rst b/core/merchant/get-private-statistics-counter-SLUG.rst @@ -6,7 +6,7 @@ SLUG will be returned. Since protocol **v25**. - **Required permission:** ``statistics-read`` + **Required permission:** ``statistics-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-statistics-report-NAME.rst b/core/merchant/get-private-statistics-report-NAME.rst @@ -14,7 +14,7 @@ The overall endpoint family exists since protocol **v25**. - **Required permission:** ``statistics-read`` + **Required permission:** ``statistics-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-templates-TEMPLATE_ID.rst b/core/merchant/get-private-templates-TEMPLATE_ID.rst @@ -3,7 +3,7 @@ This is used to obtain detailed information about a specific template. - **Required permission:** ``templates-read`` + **Required permission:** ``templates-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-templates.rst b/core/merchant/get-private-templates.rst @@ -3,7 +3,7 @@ This is used to return the list of all the templates. - **Required permission:** ``templates-read`` + **Required permission:** ``templates-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst b/core/merchant/get-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst @@ -2,7 +2,7 @@ This is used to get detailed information about a specific token family. - **Required permission:** ``tokenfamilies-read`` + **Required permission:** ``tokenfamilies-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-tokenfamilies.rst b/core/merchant/get-private-tokenfamilies.rst @@ -2,7 +2,7 @@ This is used to list all configured token families for an instance. - **Required permission:** ``tokenfamilies-read`` + **Required permission:** ``tokenfamilies-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-tokens.rst b/core/merchant/get-private-tokens.rst @@ -4,7 +4,7 @@ @since **v19** - **Required permission**: ``tokens-read`` + **Required permission:** ``tokens-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** @@ -50,7 +50,7 @@ expiration: Timestamp; // Scope for the token. - scope: "readonly" | "readwrite" | ...; + scope: TokenScope; // Is the token refreshable into a new token during its // validity? diff --git a/core/merchant/get-private-transfers.rst b/core/merchant/get-private-transfers.rst @@ -5,7 +5,7 @@ Since protocol **v20** this endpoint is only about actually confirmed wire transfers. - **Required permission:** ``transfers-read`` + **Required permission:** ``transfers-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/get-private-units-UNIT.rst b/core/merchant/get-private-units-UNIT.rst @@ -2,7 +2,7 @@ Fetch details for a single measurement unit. - **Required permission:** ``units-read`` + **Required permission:** ``units-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-units.rst b/core/merchant/get-private-units.rst @@ -2,7 +2,7 @@ Returns the list of measurement units available to an instance. - **Required permission:** ``units-read`` + **Required permission:** ``units-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-webhooks-WEBHOOK_ID.rst b/core/merchant/get-private-webhooks-WEBHOOK_ID.rst @@ -2,7 +2,7 @@ This is used to obtain detailed information about a specific webhook. - **Required permission:** ``webhooks-read`` + **Required permission:** ``webhooks-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/get-private-webhooks.rst b/core/merchant/get-private-webhooks.rst @@ -2,7 +2,7 @@ This is used to return all the webhooks that are present in our backend. - **Required permission:** ``webhooks-read`` + **Required permission:** ``webhooks-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Response:** diff --git a/core/merchant/patch-management-instances-INSTANCE.rst b/core/merchant/patch-management-instances-INSTANCE.rst @@ -6,7 +6,7 @@ that matches either the credential required by the instance being modified OR the ``admin`` instance, depending on the access path used. - **Required permission:** ``instances-token-write`` + **Required permission:** ``instances-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request** diff --git a/core/merchant/patch-private-accounts-H_WIRE.rst b/core/merchant/patch-private-accounts-H_WIRE.rst @@ -2,7 +2,7 @@ This is used to update a bank account. - **Required permission:** ``accounts-write`` + **Required permission:** ``accounts-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-categories-CATEGORY_ID.rst b/core/merchant/patch-private-categories-CATEGORY_ID.rst @@ -3,7 +3,7 @@ This is used to edit a category. Since API version **v16**. - **Required permission:** ``categories-write`` + **Required permission:** ``categories-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-fountains-FOUNTAIN_ID.rst b/core/merchant/patch-private-fountains-FOUNTAIN_ID.rst @@ -6,7 +6,7 @@ their next ``GET /fountain/info`` poll. This endpoint is available since protocol **vTokenFountains**. - **Required permission:** ``fountains-write`` + **Required permission:** ``fountains-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-groups-GROUP_ID.rst b/core/merchant/patch-private-groups-GROUP_ID.rst @@ -2,7 +2,7 @@ This is used to update a group. - **Required permission:** ``groups-write`` + **Required permission:** ``groups-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-orders-ORDER_ID-forget.rst b/core/merchant/patch-private-orders-ORDER_ID-forget.rst @@ -3,7 +3,7 @@ Forget fields in an order's contract terms that the merchant no longer needs. - **Required permission:** ``orders-write`` + **Required permission:** ``orders-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-otp-devices-DEVICE_ID.rst b/core/merchant/patch-private-otp-devices-DEVICE_ID.rst @@ -2,7 +2,7 @@ This is used to update an OTP device. It is useful when we need to change information in the OTP device or when we have mistake some information. - **Required permission:** ``otp-devices-write`` + **Required permission:** ``otp-devices-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-pots-POT_ID.rst b/core/merchant/patch-private-pots-POT_ID.rst @@ -2,7 +2,7 @@ This is used to update a pot. - **Required permission:** ``pots-write`` + **Required permission:** ``pots-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-products-PRODUCT_ID.rst b/core/merchant/patch-private-products-PRODUCT_ID.rst @@ -11,7 +11,7 @@ timestamp to indicate no intention/possibility of restocking, while a time of zero is used to indicate "unknown". - **Required permission:** ``products-write`` + **Required permission:** ``products-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-reports-REPORT_ID.rst b/core/merchant/patch-private-reports-REPORT_ID.rst @@ -2,7 +2,7 @@ This is used to update a scheduled report. - **Required permission:** ``reports-write`` + **Required permission:** ``reports-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-templates-TEMPLATE_ID.rst b/core/merchant/patch-private-templates-TEMPLATE_ID.rst @@ -2,7 +2,7 @@ This is used to update a template. It is useful when we need to change information in the template or when we have mistake some information. - **Required permission:** ``templates-write`` + **Required permission:** ``templates-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst b/core/merchant/patch-private-tokenfamilies-TOKEN_FAMILY_SLUG.rst @@ -2,7 +2,7 @@ This is used to update a token family. - **Required permission:** ``tokenfamilies-write`` + **Required permission:** ``tokenfamilies-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-units-UNIT.rst b/core/merchant/patch-private-units-UNIT.rst @@ -2,7 +2,7 @@ Update attributes of a measurement unit. - **Required permission:** ``units-write`` + **Required permission:** ``units-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/patch-private-webhooks-WEBHOOK_ID.rst b/core/merchant/patch-private-webhooks-WEBHOOK_ID.rst @@ -2,7 +2,7 @@ This is used to update a webhook. - **Required permission:** ``webhooks-write`` + **Required permission:** ``webhooks-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-management-instances-INSTANCE-auth.rst b/core/merchant/post-management-instances-INSTANCE-auth.rst @@ -6,7 +6,8 @@ that matches either the credential required by the instance being modified OR the ``admin`` instance, depending on the access path used. - **Required permission:** ``instances-auth-write`` + **Required permission:** ``auth-write`` on the ``/private`` path, + ``instances-auth-write`` on the ``/management/`` path (see :ref:`Scopes <merchant-api-scopes>`) **Request** the request must be an `InstanceAuthConfigurationMessage`. diff --git a/core/merchant/post-management-instances.rst b/core/merchant/post-management-instances.rst @@ -5,7 +5,7 @@ This request will be used to create a new merchant instance in the backend. It is only available for the implicit ``admin`` instance. - **Required permission:** ``instances-write`` + **Required permission:** ``instances-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-accept-tos-early.rst b/core/merchant/post-private-accept-tos-early.rst @@ -13,7 +13,7 @@ Introduced in **v31**. - **Required permission:** ``accounts-write`` + **Required permission:** ``accounts-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-accounts-H_WIRE-kycauth.rst b/core/merchant/post-private-accounts-H_WIRE-kycauth.rst @@ -15,7 +15,7 @@ Since protocol **v28**. - **Required permission:** ``accounts-read`` + **Required permission:** ``accounts-read`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-accounts.rst b/core/merchant/post-private-accounts.rst @@ -2,7 +2,7 @@ This is used to add an account to an instance. - **Required permission:** ``accounts-write`` + **Required permission:** ``accounts-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-categories.rst b/core/merchant/post-private-categories.rst @@ -3,7 +3,7 @@ This is used to create a new category for the inventory. Since API version **v16**. - **Required permission:** ``categories-write`` + **Required permission:** ``categories-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-donau.rst b/core/merchant/post-private-donau.rst @@ -4,7 +4,7 @@ The backend fetches and validates the charity’s metadata from the given Donau service before persisting the link. - **Required permission:** ``donau-write`` + **Required permission:** ``donau-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-fountains.rst b/core/merchant/post-private-fountains.rst @@ -6,7 +6,7 @@ (see :doc:`DD 98 </design-documents/098-token-fountains>`). This endpoint is available since protocol **vTokenFountains**. - **Required permission:** ``fountains-write`` + **Required permission:** ``fountains-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-groups.rst b/core/merchant/post-private-groups.rst @@ -2,7 +2,7 @@ This is used to create a group. - **Required permission:** ``groups-write`` + **Required permission:** ``groups-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-orders-ORDER_ID-collect.rst b/core/merchant/post-private-orders-ORDER_ID-collect.rst @@ -25,7 +25,7 @@ ``amount`` must be zero and, for v1 contracts, the selected choice must have no ``inputs`` and no ``outputs``. - **Required permission:** ``orders-write`` + **Required permission:** ``orders-write`` (see :ref:`Scopes <merchant-api-scopes>`) Since protocol **vMixedPayments**. diff --git a/core/merchant/post-private-orders-ORDER_ID-refund-external.rst b/core/merchant/post-private-orders-ORDER_ID-refund-external.rst @@ -29,7 +29,7 @@ so a duplicate would permanently consume part of the amount that may still be refunded for the order. - **Required permission:** ``orders-refund`` + **Required permission:** ``orders-refund`` (see :ref:`Scopes <merchant-api-scopes>`) Since protocol **vMixedPayments**. diff --git a/core/merchant/post-private-orders-ORDER_ID-refund.rst b/core/merchant/post-private-orders-ORDER_ID-refund.rst @@ -7,7 +7,7 @@ the cumulative Taler refund must not exceed the full order total minus those external refunds. - **Required permission:** ``orders-refund`` + **Required permission:** ``orders-refund`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-orders.rst b/core/merchant/post-private-orders.rst @@ -22,7 +22,7 @@ unique for every order: there might be varying parameters such as the session id. - **Required permission:** ``orders-write`` + **Required permission:** ``orders-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-otp-devices.rst b/core/merchant/post-private-otp-devices.rst @@ -2,7 +2,7 @@ This is used to associate an OTP device with an instance. - **Required permission:** ``otp-devices-write`` + **Required permission:** ``otp-devices-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-pots.rst b/core/merchant/post-private-pots.rst @@ -2,7 +2,7 @@ This is used to create a pot. - **Required permission:** ``pots-write`` + **Required permission:** ``pots-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-products-PRODUCT_ID-lock.rst b/core/merchant/post-private-products-PRODUCT_ID-lock.rst @@ -16,7 +16,7 @@ If an order is for fewer items than originally locked, the difference is automatically unlocked. - **Required permission:** ``products-lock`` + **Required permission:** ``products-lock`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-products.rst b/core/merchant/post-private-products.rst @@ -2,7 +2,7 @@ This is used to add a product to the inventory. - **Required permission:** ``products-write`` + **Required permission:** ``products-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-reports.rst b/core/merchant/post-private-reports.rst @@ -2,7 +2,7 @@ This is used to schedule the generation of periodic reports. - **Required permission:** ``reports-write`` + **Required permission:** ``reports-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-templates.rst b/core/merchant/post-private-templates.rst @@ -2,7 +2,7 @@ This is used to create a template. - **Required permission:** ``templates-write`` + **Required permission:** ``templates-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-token.rst b/core/merchant/post-private-token.rst @@ -9,7 +9,7 @@ along with ``$INSTANCE`` as username. - **Required permission:** ``token-refresh`` if accessed using a Bearer token. + **Required permission:** ``token-refresh`` if accessed using a Bearer token (see :ref:`Scopes <merchant-api-scopes>`). **Request:** @@ -42,8 +42,8 @@ .. ts:def:: LoginTokenRequest interface LoginTokenRequest { - // Scope of the token (which kinds of operations it will allow) - scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full"; + // Scope of the token (which kinds of operations it will allow). + scope: TokenScope; // Server may impose its own upper bound // on the token validity duration @@ -71,8 +71,8 @@ // **Since v19** access_token: string; - // Scope of the token (which kinds of operations it will allow) - scope: "readonly" | "write" | "all" | "order-simple" | "order-pos" | "order-mgmt" | "order-full"; + // Scope of the token (which kinds of operations it will allow). + scope: TokenScope; // Server may impose its own upper bound // on the token validity duration diff --git a/core/merchant/post-private-tokenfamilies.rst b/core/merchant/post-private-tokenfamilies.rst @@ -2,7 +2,7 @@ This is used to create a token family. - **Required permission:** ``tokenfamilies-write`` + **Required permission:** ``tokenfamilies-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-transfers.rst b/core/merchant/post-private-transfers.rst @@ -5,7 +5,7 @@ transfer information from the merchant's database (assuming we got a non-error response from the exchange before). - **Required permission:** ``transfers-write`` + **Required permission:** ``transfers-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-units.rst b/core/merchant/post-private-units.rst @@ -2,7 +2,7 @@ Create a custom measurement unit or reactivate a previously disabled one. - **Required permission:** ``units-write`` + **Required permission:** ``units-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:** diff --git a/core/merchant/post-private-webhooks.rst b/core/merchant/post-private-webhooks.rst @@ -2,7 +2,7 @@ This is used to create a webhook. - **Required permission:** ``webhooks-write`` + **Required permission:** ``webhooks-write`` (see :ref:`Scopes <merchant-api-scopes>`) **Request:**