commit ee1a57ba8cc95e0babc0aa7707974e80d7d5a592
parent 964a27acc72cec21306169c757d1abd668a926af
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Thu, 19 Jun 2025 09:53:21 +0200
refresh DD49 with merchant changes to scope
Diffstat:
1 file changed, 39 insertions(+), 1 deletion(-)
diff --git a/design-documents/049-auth.rst b/design-documents/049-auth.rst
@@ -57,6 +57,7 @@ Token Creation
// validity?
// Refreshable tokens effectively provide indefinite
// access if they are refreshed in time.
+ // Deprecated, use ":refreshable" suffix in scope instead.
refreshable?: boolean;
// Optional token description
@@ -94,7 +95,6 @@ the token endpoint.
.. http:delete:: /${RESOURCE...}/token
Invalidate the access token that is being used to make the request.
-
**Authentication:** The client must authenticate
with a valid access token.
@@ -159,6 +159,44 @@ List existing token informations.
row_id: Integer;
}
+Permissions
+===========
+
+Each API request to an endpoint **may** be associated with a *permission*.
+A permission is a descriptive string, e.g. ``orders-read``
+If no permission is defined for a request, the endpoint, no access control is enforced.
+
+Permission strings best practice include that *read-only* access end with the suffix ``-read``, e.g. ``orders-read``.
+If the access to the endpoint modifies the state it is suffixed with ``-write``, e.g. ``orders-write``.
+Special permissions may deviate from this.
+
+In the API documentaction where the **Request** to an endpoint is defined, **Required permission** entry should be added.
+See the Merchant API for examples.
+
+Scopes
+======
+
+A ``scope`` is a set of permissions that is associated with a token.
+The scope is provided when requesting the token, see `TokenRequest`.
+
+Default scopes are defined by the component.
+Here are some *examples* of possible scopes:
+
+* ``readonly``: ``*-read`` -- This wildcard match will grant access to all endpoints protected with a permission that has the ``-read`` suffix.
+* ``admin``: ``*`` -- This matches all permissions, essentially the *key to the kingdom*.
+* ``orders-simple``: ``orders-read,orders-write`` -- Access to reading and writing orders.
+* ``orders-full``: ``orders-read,orders-write,orders-refund`` -- Like ``orders-simple``, but also allows for refunds.
+
+In the merchant component, scopes are currently hard-coded. In the future, additional scopes may be configurable
+through configuration files and/or default scopes overridden.
+
+Token refresh
+=============
+
+Tokens may be requested to be refreshable.
+In older API versions this was achieved by setting the ``refreshable`` field in the `TokenRequest`.
+In recent API versions this is achieved by suffixing the requested scope with ``:refreshable``, e.g. ``orders-full:refreshable``.
+
Definition of Done
==================
