commit 889ca899ad1c4797f0f61925221047e70bb63f88
parent 4c6ff3f022ddde57f63d660c3ad737b00476f558
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Thu, 19 Jun 2025 10:00:33 +0200
more clarification
Diffstat:
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/design-documents/049-auth.rst b/design-documents/049-auth.rst
@@ -166,9 +166,11 @@ 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, no access control is enforced.
+Each component API **must** define and document appropriate permissions for its requests.
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.
+Two endpoints **may** use the same permission.
In the API documentaction where the **Request** to an endpoint is defined, **Required permission** entry should be added.
See the Merchant API for examples.
@@ -179,7 +181,7 @@ 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.
+Default scopes that can be requested in a `TokenRequest` are or rather **must** be defined and documented 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.
