Token Permissions

What scopes to enable on your Forgejo/Gitea personal-access token. For how madtea stores that token and the credential-safety guarantees, see credential-safety.md. For how to report a security issue, see ../SECURITY.md.

What to enable

madtea works against three rough token tiers. Pick the smallest one that covers what you’ll do.

Read-only (browse, list, search):

read:repository
read:issue
read:user

Standard (typical day-to-day: create PRs/issues, merge, comment, mark notifications read):

read:repository + write:repository
read:issue + write:issue
read:notification + write:notification
read:user

Full (org administration, packages, webhooks, branch protection, admin domains):

All Standard scopes, plus:
read:organization + write:organization (org/team management, org labels, org webhooks)
read:package + write:package (package registry)
read:admin + write:admin (site admin commands — requires the token owner to be a site admin)
Repo admin permission on the target repos for: transfer, delete, webhooks, branch/tag protection, collaborators

If you’re not sure, start with Standard. madtea’s 403 errors include a hint about the missing scope.

What madtea auth login --web mints. The browser-OAuth flow mints a least-privilege token: the Standard tier above plus read:organization (needed so org-label names resolve). It does not request write:organization, packages, or admin scopes. If you need broader scope than that, mint a token manually in the forge web UI (Settings → Applications → Manage Access Tokens) with the tiers above and use the paste-based madtea auth login.

Scope reference

Scope	What it unlocks
`read:repository`	Read files, branches, tags, commits, PRs, PR reviews, status checks
`write:repository`	Push, create/merge PRs, manage releases, status checks, branch/tag protection (with admin perm), file CRUD via API
`read:issue`	List/read issues, comments, attachments, dependencies, reactions, time entries
`write:issue`	Create/edit issues, comments, attachments, reactions, time, deadlines, locks, pins, subscriptions
`read:notification`	List notifications
`write:notification`	Mark notifications read
`read:user`	Read user info (`whoami`, profile, followers, starred, subscriptions)
`read:organization`	Read org metadata, members, teams, hooks
`write:organization`	Manage teams/members/blocks/hooks/secrets/variables/runners, org labels
`read:package` / `write:package`	List / delete / link packages in the package registry
`read:admin` / `write:admin`	Site administration commands (users, cron, system hooks, runners across the instance)

The activitypub, misc, and admin scope families exist in the Forgejo/Gitea token UI too; they’re rarely needed and madtea will tell you when one is missing.

Troubleshooting

API error 403: forbidden — your token is missing a scope. madtea’s error message includes a hint about the required scope; re-create the token with that scope enabled.

API error 401: unauthorized — token is invalid or expired. Re-run madtea auth login.

Push or PR-create fails despite write:repository — the target repo also requires write collaborator permission for your user. The token scope is necessary but not sufficient.

Admin commands return 403 — read:admin / write:admin only work if the token owner is a site admin in Forgejo/Gitea. The scope check passes; the admin check inside the endpoint fails.

Canonical source: docs/PERMISSIONS.md in the madtea repo.