centersl/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-03-27 14:11:03 +07:00
Code Issues Packages Projects Releases Wiki Activity

Clarify package permissions and tokens scopes as discussed in https://github.com/go-gitea/gitea/issues/32048 (#72)

Browse Source 
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>
This commit is contained in:
FrostKiwi
2025-11-20 22:16:00 +00:00
committed by Lunny Xiao
parent 98a7ea3f53
commit 072331ecae
3 changed files with 26 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/development/api-usage.md
View File

@@ -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).