Forgejo · Codeberg · Gitea · access tokens · Checked October 24, 2026

Forgejo and Gitea: "token does not have at least one of required scope(s)"

The access token is valid, but it was created without a permission (scope) this API call needs. The server refuses the call with HTTP 403 and names the scopes that would be accepted; any one of them is enough. Create a new token that has it, and replace the old one wherever it was entered.

The whole answer

From Forgejo (a public report against code.forgejo.org), and the same from Gitea 1.22 and earlier:

HTTP 403
{"message": "token does not have at least one of required scope(s): [read:organization]",
 "url": "https://code.forgejo.org/api/swagger"}

Gitea 1.23 and later also says what the token has (a public report):

{"message": "token does not have at least one of required scope(s), required=[read:user], token scope=write:package,write:issue,write:repository",
 "url": "https://<gitea-host>/api/swagger"}

The list in brackets is what to add. In the source, read is required for GET and write for POST, PUT, PATCH and DELETE, so a token with only read:repository gets this answer on its first merge or review (Forgejo, Gitea). Many tools show only "403 Forbidden"; to see the message, call the address that failed with curl:

curl -i -H "Authorization: token your-token" "https://codeberg.org/api/v1/the/address/that/failed"

If the answer is 401 instead, with "token is required" or a message about a user or token that does not exist, the token did not arrive or the server does not know it: see 401 and the unknown-token messages.

Scopes that pull request tools need

From Forgejo's token scope documentation, which groups the scopes by API route:

repository: /repos/* except the issue routes: pull requests, files, commits, reviews and merging. read:repository to read them, write:repository to create, review and merge.
issue: issues/*, labels and milestones. A pull request is also an issue, so its conversation (comments and timeline) comes through these routes: read:issue to read it, write:issue to comment. A public report shows reading a pull request's timeline refused with [read:issue].
user: /user and /users/*. Many tools ask /user first, to learn who you are, and fail on that call alone without read:user (as in a report against Codeberg).
organization: orgs/* and teams/*, for tools that list your organizations or teams.

write includes read in the same group, but the groups do not include each other: write:repository does not let a token read the conversation, which needs read:issue.

Create a token with the scope

Your avatar, Settings, Applications (the address is /user/settings/applications on your server, for example https://codeberg.org/user/settings/applications).
Under Access tokens, Generate new token: a name, Repository and organization access, then under Select permissions set each group to Read or Read and write: the ones you had, plus every scope from the message.
Generate token and copy it. The server says it will not be shown again.
Put the new token where the old one was, and Delete the old one on the same page.

Forgejo and Gitea pull requests in IntelliJ IDEA

Pull Request Inbox for Forgejo and Gitea, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, reads with read:repository, read:issue and read:user, and approves, comments and merges with write:repository and write:issue. When the server answers with this message, the plugin shows it, says which scopes the token needs, and offers to open its settings, which link to your server's token page. The review inbox, diffs and conversations are free; approving, commenting and merging are Pro (US$1.50 a month, with a 30-day trial).

Forgejo, Gitea and Codeberg are names of their respective owners; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by the Forgejo project, Codeberg e.V., the Gitea project or JetBrains.