From 072331ecae4fdfbba0417300cbe48f334366cf8b Mon Sep 17 00:00:00 2001
From: FrostKiwi <frostkiwi@noreply.gitea.com>
Date: Thu, 20 Nov 2025 22:16:00 +0000
Subject: [PATCH] Clarify package permissions and tokens scopes as discussed in
 https://github.com/go-gitea/gitea/issues/32048 (#72)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This adds explanations, that were missing regarding Token scopes and the packages feature requiring a token with said scope. Also added a missing explanation, that tokens can be created in the user interface, not just the API. The reason this PR is created was due to misunderstandings around the package feature, that arose during the discussion in https://github.com/go-gitea/gitea/issues/32048 .
This PR aims to clarify the misunderstood points around tokens, scopes and the package feature.

During the creation of this PR bug https://github.com/go-gitea/gitea/issues/32078 was found, the scopes are always reported as `null` during the response of the initial `POST` to create the token.

Co-authored-by: Wladislav ヴラド Artsimovich <wladislav.artsimovich@dmgmori.co.jp>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/72
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: FrostKiwi <frostkiwi@noreply.gitea.com>
Co-committed-by: FrostKiwi <frostkiwi@noreply.gitea.com>
---
 docs/development/api-usage.md   | 23 +++++++++++++++++++++++
 docs/usage/packages/npm.md      |  2 +-
 docs/usage/packages/overview.md |  2 ++
 3 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/development/api-usage.md b/docs/development/api-usage.md
index ed026f8a..d09b3ded 100644
--- a/docs/development/api-usage.md
+++ b/docs/development/api-usage.md
@@ -27,7 +27,13 @@ Gitea parses queries and headers to find the token in
 [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
 
 ## Generating and listing API tokens
+API tokens can be created either in the user interface or via the API. Tokens have by default limited permissions and it is important to create tokens with the correct permissions for your task.
+### User Interface
+Tokens can be created via the `Manage Access Tokens` dialog, accessed via `User Settings` / `Applications` or via the link `gitea-domain.example/user/settings/applications`. The interface allows you to create tokens and manage their permissions via the `Select permissions` sub-menu.
 
+Once created, the token is displayed in a toast message above the `Manage Access Tokens` dialog. Please note, that you can view this toast only once and it is not possible to redisplay the token for security reasons.
+
+### Token API
 A new token can be generated with a `POST` request to
 `/users/:name/tokens`.
 
@@ -50,6 +56,23 @@ $ curl --url https://yourusername:password@gitea.your.host/api/v1/users/<usernam
 [{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
 ```
 
+By default, this creates a token with very limited permissions. To complete your tasks, your token may require extra permissions. These permissions are created via the json variable `scopes`, which takes an array of permissions as strings. Eg.: `"scopes":["all"]`. Possible permissions, as reflected in the user interface are:
+- `activitypub`
+- `admin`
+- `issue`
+- `misc`
+- `notification`
+- `organization`
+- `package`
+- `repository`
+- `user`
+
+Each permission may be set to `read` or `write`. `write` implies both Read & Write. To set permissions you write the permissions string as `<read or write>:<permission name>`, eg.: `write:package` or `read:notification`. A properly formatted API call may look like:
+```sh
+$ curl -H "Content-Type: application/json" -d '{"name":"test", "scopes":["write:package", "read:notification"]}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
+```
+Special permissions `all` may be specified as `"scopes":["all"]`, which sets all permissions to both Read & Write.
+
 To use the API with basic authentication with two factor authentication
 enabled, you'll need to send an additional header that contains the one
 time password (6 digitrotating token).
diff --git a/docs/usage/packages/npm.md b/docs/usage/packages/npm.md
index b518cc7d..1f0cb59e 100644
--- a/docs/usage/packages/npm.md
+++ b/docs/usage/packages/npm.md
@@ -29,7 +29,7 @@ npm config set -- '//gitea.example.com/api/packages/{owner}/npm/:_authToken' "{t
 | ------------ | ----------- |
 | `scope`      | The scope of the packages. |
 | `owner`      | The owner of the package. |
-| `token`      | Your [personal access token](development/api-usage.md#authentication). |
+| `token`      | Your [personal access token](development/api-usage.md#authentication). With `package` permissions. |
 
 For example:
 
diff --git a/docs/usage/packages/overview.md b/docs/usage/packages/overview.md
index 7bdf6fe6..9cb9b11d 100644
--- a/docs/usage/packages/overview.md
+++ b/docs/usage/packages/overview.md
@@ -56,6 +56,8 @@ and shows a link to the repository on the package site (as well as a link to the
 | **read** access    | public, if user is public too; otherwise for this user only | public, if org is public, otherwise for org members only |
 | **write** access   | owner only | org members with admin or write access to the org |
 
+Please note, that your respective package manager needs to have a [personal access token](development/api-usage.md#authentication) with the permissions `package` set to either Read or Read & Write to download and publish packages respectively.
+
 N.B.: These access restrictions are [subject to change](https://github.com/go-gitea/gitea/issues/19270), where more finegrained control will be added via a dedicated organization team permission.
 
 ## Create or upload a package