forgejo-docs/docs/user/token-scope.md

---
title: 'Access Token scope'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/development/oauth2-provider.en-us.md'
---

Forgejo supports scoped access tokens, which allow users to restrict tokens to operate only on selected url routes. Scopes are grouped by high-level API routes, and further refined to the following:

- `read`: `GET` routes
- `write`: `POST`, `PUT`, `PATCH`, and `DELETE` routes (in addition to `GET`)

Forgejo token scopes are as follows:

| Name                                      | Description                                                                                                                                          |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **(no scope)**                            | Not supported. A scope is required even for public repositories.                                                                                     |
| **activitypub**                           | `activitypub` API routes: ActivityPub related operations.                                                                                            |
| &nbsp;&nbsp;&nbsp; **read:activitypub**   | Grants read access for ActivityPub operations.                                                                                                       |
| &nbsp;&nbsp;&nbsp; **write:activitypub**  | Grants read/write/delete access for ActivityPub operations.                                                                                          |
| **admin**                                 | `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts).                                                          |
| &nbsp;&nbsp;&nbsp; **read:admin**         | Grants read access for admin operations, such as getting cron jobs or registered user emails.                                                        |
| &nbsp;&nbsp;&nbsp; **write:admin**        | Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts.                                           |
| **issue**                                 | `issues/*`, `labels/*`, `milestones/*` API routes: Issue-related operations.                                                                         |
| &nbsp;&nbsp;&nbsp; **read:issue**         | Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones.                                         |
| &nbsp;&nbsp;&nbsp; **write:issue**        | Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones.           |
| **misc**                                  | miscellaneous and settings top-level API routes.                                                                                                     |
| &nbsp;&nbsp;&nbsp; **read:misc**          | Grants read access to miscellaneous operations, such as getting label and gitignore templates.                                                       |
| &nbsp;&nbsp;&nbsp; **write:misc**         | Grants read/write/delete access to miscellaneous operations, such as markup utility operations.                                                      |
| **notification**                          | `notification/*` API routes: user notification operations.                                                                                           |
| &nbsp;&nbsp;&nbsp; **read:notification**  | Grants read access to user notifications, such as which notifications users are subscribed to and read new notifications.                            |
| &nbsp;&nbsp;&nbsp; **write:notification** | Grants read/write/delete access to user notifications, such as marking notifications as read.                                                        |
| **organization**                          | `orgs/*` and `teams/*` API routes: Organization and team management operations.                                                                      |
| &nbsp;&nbsp;&nbsp; **read:organization**  | Grants read access to org and team status, such as listing all orgs a user has visibility to, teams, and team members.                               |
| &nbsp;&nbsp;&nbsp; **write:organization** | Grants read/write/delete access to org and team status, such as creating and updating teams and updating org settings.                               |
| **package**                               | `/packages/*` API routes: Packages operations                                                                                                        |
| &nbsp;&nbsp;&nbsp; **read:package**       | Grants read access to package operations, such as reading and downloading available packages.                                                        |
| &nbsp;&nbsp;&nbsp; **write:package**      | Grants read/write/delete access to package operations. Currently the same as `read:package`.                                                         |
| **repository**                            | `/repos/*` API routes except `/repos/issues/*`: Repository file, pull-request, and release operations.                                               |
| &nbsp;&nbsp;&nbsp; **read:repository**    | Grants read access to repository operations, such as getting repository files, releases, collaborators.                                              |
| &nbsp;&nbsp;&nbsp; **write:repository**   | Grants read/write/delete access to repository operations, such as getting updating repository files, creating pull requests, updating collaborators. |
| **user**                                  | `/user/*` and `/users/*` API routes: User-related operations.                                                                                        |
| &nbsp;&nbsp;&nbsp; **read:user**          | Grants read access to user operations, such as getting user repo subscriptions and user settings.                                                    |
| &nbsp;&nbsp;&nbsp; **write:user**         | Grants read/write/delete access to user operations, such as updating user repo subscriptions, followed users, and user settings.                     |
docs: user: authentication: move token scope out of the oauth2 section # Conflicts: # user/token-scope.md 2023-07-24 10:14:11 -04:00			`---`
			`title: 'Access Token scope'`
			`license: 'Apache-2.0'`
sync with Gitea abe8fe352711601fbcd24bf4505f7e0b81a93c5d git diff bd4c7ce578956d9839309b16753bd5505b63b2e3..abe8fe352711601fbcd24bf4505f7e0b81a93c5d -- $(find . -type f -name 'en-us') (cherry picked from commit 0b81e66c45cc6a7a24306a948707e8ee01361876) 2023-10-08 09:11:22 -04:00			`origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/development/oauth2-provider.en-us.md'`
docs: user: authentication: move token scope out of the oauth2 section # Conflicts: # user/token-scope.md 2023-07-24 10:14:11 -04:00			`---`

			`Forgejo supports scoped access tokens, which allow users to restrict tokens to operate only on selected url routes. Scopes are grouped by high-level API routes, and further refined to the following:`

			- `read`: `GET` routes
			- `write`: `POST`, `PUT`, `PATCH`, and `DELETE` routes (in addition to `GET`)

			`Forgejo token scopes are as follows:`

			`\| Name \| Description \|`
			`\| ----------------------------------------- \| ---------------------------------------------------------------------------------------------------------------------------------------------------- \|`
			`\| (no scope) \| Not supported. A scope is required even for public repositories. \|`
			\| activitypub \| `activitypub` API routes: ActivityPub related operations. \|
			`\|     read:activitypub \| Grants read access for ActivityPub operations. \|`
			`\|     write:activitypub \| Grants read/write/delete access for ActivityPub operations. \|`
			\| admin \| `/admin/*` API routes: Site-wide administrative operations (hidden for non-admin accounts). \|
			`\|     read:admin \| Grants read access for admin operations, such as getting cron jobs or registered user emails. \|`
			`\|     write:admin \| Grants read/write/delete access for admin operations, such as running cron jobs or updating user accounts. \|`
			\| issue \| `issues/`, `labels/`, `milestones/*` API routes: Issue-related operations. \|
			`\|     read:issue \| Grants read access for issues operations, such as getting issue comments, issue attachments, and milestones. \|`
			`\|     write:issue \| Grants read/write/delete access for issues operations, such as posting or editing an issue comment or attachment, and updating milestones. \|`
			`\| misc \| miscellaneous and settings top-level API routes. \|`
			`\|     read:misc \| Grants read access to miscellaneous operations, such as getting label and gitignore templates. \|`
			`\|     write:misc \| Grants read/write/delete access to miscellaneous operations, such as markup utility operations. \|`
			\| notification \| `notification/*` API routes: user notification operations. \|
			`\|     read:notification \| Grants read access to user notifications, such as which notifications users are subscribed to and read new notifications. \|`
			`\|     write:notification \| Grants read/write/delete access to user notifications, such as marking notifications as read. \|`
			\| organization \| `orgs/` and `teams/` API routes: Organization and team management operations. \|
			`\|     read:organization \| Grants read access to org and team status, such as listing all orgs a user has visibility to, teams, and team members. \|`
			`\|     write:organization \| Grants read/write/delete access to org and team status, such as creating and updating teams and updating org settings. \|`
			\| package \| `/packages/*` API routes: Packages operations \|
			`\|     read:package \| Grants read access to package operations, such as reading and downloading available packages. \|`
			\|     write:package \| Grants read/write/delete access to package operations. Currently the same as `read:package`. \|
			\| repository \| `/repos/` API routes except `/repos/issues/`: Repository file, pull-request, and release operations. \|
			`\|     read:repository \| Grants read access to repository operations, such as getting repository files, releases, collaborators. \|`
			`\|     write:repository \| Grants read/write/delete access to repository operations, such as getting updating repository files, creating pull requests, updating collaborators. \|`
			\| user \| `/user/` and `/users/` API routes: User-related operations. \|
			`\|     read:user \| Grants read access to user operations, such as getting user repo subscriptions and user settings. \|`
			`\|     write:user \| Grants read/write/delete access to user operations, such as updating user repo subscriptions, followed users, and user settings. \|`