Skip to content
Try Gitea Cloud ☁️ for 30 days → Accelerate your Development & Deploys!
Support
This is the documentation of 27.3.11, which is no longer the latest release. See the latest release.

Fine-grained Access Tokens

A fine-grained access token is a personal access token that acts on one resource owner (you or one organization), a list of repositories you choose and a list of permissions you choose, so a leaked token does far less damage than a classic one.

Classic tokens keep working and are not retired automatically. A valid license is required.

Classic token Fine-grained token
Format 40 hex characters gitea_pat_ + 40 hex characters
Reach everything the holder can reach, within its scopes one owner (the holder or one organization), the selected repositories, the selected permissions
Expiry optional (own expiry, instance lifetime limit) 30 days by default, 1-366 days or none
Organization approval never always, for a token owned by an organization
Count unlimited 50 per user

Use fine-grained tokens whenever you can. Keep classic tokens for scripts that need several owners at once.

Open Settings > Applications and use the fine-grained tokens section.

  1. Choose a name (up to 40 characters), an optional description and an expiration.
  2. Choose the resource owner: yourself or an organization you belong to. A token only acts on resources of its owner.
  3. Choose the repository access: public repositories only, all repositories of the owner, or the repositories you list as owner/name. A token limited to public repositories is read-only: the form disables every write permission and the API refuses them.
  4. Choose the permissions (read or write per category). admin and misc are not available. organization is only shown when the owner is an organization, and permissions that need a personal owner (for example write:activitypub) are hidden when the owner is an organization.
  5. For a token owned by an organization, say why you need it. Until an approver of the organization approves it, the token only reads public resources of that organization.

The token is shown once. Only a hash is stored and nobody can read it back, not even an administrator; if you lose it, regenerate it. For safety, neither the UI nor the API shows any characters of a fine-grained token (no first or last characters); tell tokens apart by name and description.

/user/settings/applications?name=ci&description=deploy&target_name=my-org&expires_in=90&repo_selection=all&repository=read

expires_in is one of 7, 30, 60, 90, 366 or none; any other value falls back to 30.

The effective access is the intersection of the token’s grant and your own access: if you lose access to a repository, so does the token. Outside the grant, only public read access remains.

  • Listings (for example /user/repos) only show public repositories for a fine-grained token; ask for a private repository by name to reach it.
  • Packages belong to an owner, not a repository: a token with the package permission reaches the packages of its owner.
  • A fine-grained token cannot create, approve or revoke tokens, and a token owned by an organization has no account (user, notification) access.

You get an email 7 days and 1 day before a token expires.

POST /api/v1/users/{user}/tokens
{"name": "ci", "kind": "fine_grained", "scopes": ["read:repository"], "owner": "my-org",
"repo_selection": "selected", "repositories": ["my-org/app"], "expires_in_days": 30,
"justification": "deploys the app"}

kind is classic (default) or fine_grained. Classic tokens accept expires_in_days and description too. GET /api/v1/users/{user}/tokens lists both kinds and never returns a secret.

Organization settings > Access token policy (/org/{org}/settings/token-policy):

  • Forbid classic tokens altogether: in the organization they get no more than an anonymous visitor.
  • Forbid classic tokens to write: they keep reading what their holder reads, private resources included, and change nothing. Forbidding them altogether wins over this.
  • Who can approve: the organization’s owners (the default), or its owners and the members of teams with administrator permission. Only the owners team can change this; a site administrator cannot.

The two classic options revoke nothing and can be undone at once.

Every fine-grained token owned by an organization needs an approval. There is no setting that turns this off, nobody is exempt (an owner included), and the instance has no approval setting.

Token requests (/org/{org}/token-requests) is open to every member and shows the organization settings menu on the left for owners:

  • An approver sees every token that acts on the organization and can approve or reject pending requests, or revoke tokens (singly or in bulk).
  • Any other member sees only the tokens they hold and cannot decide anything.
  • A revoked token keeps its public read access.
  • The holder is emailed about every decision.
  • A holder can decide their own request only when there is no other approver.

API: GET /api/v1/orgs/{org}/personal-access-tokens (all tokens for an approver, the own ones for another member) and, for approvers only, POST .../{id}/approve|reject|revoke. A fine-grained token cannot call these endpoints.

A site administrator does not approve tokens. They can disable, enable or delete a token, but a pending request waits for an approver of the organization. If an organization has no usable approver, give a person the owner role or put them in an administrator team.

Site Administration > Identity & Access > Access Tokens (/-/admin/access-tokens):

  • The central list shows each token with its holder, kind, owner, scopes, last use, expiry and status, never a secret or a hash. Enable, disable or delete tokens singly or in bulk; every action is audited.
  • Classic tokens: the instance can switch them off, forbid new ones or limit their lifetime; see Classic token policy.
  • A fine-grained token cannot hold the admin permission, and a site administrator’s fine-grained token acts without administrator rights. The site administration API stays with classic tokens.
  • Fine-grained tokens can have a lifetime limit (Maximum lifetime of fine-grained tokens, 0 to 366 days, 0 means no limit) but cannot be switched off for the instance or by an organization.
  • Leaked tokens: when the secret scanner finds a live token in a public repository, the token is deleted and its holder is emailed (on by default).

On the same page, the Classic token policy form controls classic tokens for the whole instance. Every setting takes effect on the next request and none of them deletes or rewrites a token.

Setting Effect
Allow classic tokens Turn it off and every classic token stops working (requests get “classic access tokens are disabled”). Nothing is deleted; turn it on again to bring them back. Default: on.
Forbid creating new classic tokens Users can no longer create classic tokens, in the web UI or through the API. Existing ones keep working. Default: off.
Maximum lifetime of classic tokens (days) 0 means no limit, otherwise 1 to 36500 days. Counted from the creation of each token and checked on every request: effective expiry = min(own expiry, created + N days). Changing N takes effect at once and can be undone.
Keep the classic tokens of site administrators that hold an admin scope usable While classic tokens are switched off or closed for creation, administrator tokens with an admin scope keep working. They must expire. Default: off.
Maximum lifetime of a classic token with an admin scope (days) 0 means no limit (default). Tokens with the all scope include the admin scope, so turning this on can stop existing automation; decide it for the whole instance.

An organization can additionally forbid classic tokens in its own scope; see Token policy.

  1. Set an instance lifetime limit for classic tokens (for example 90 days) and tell users; scripts that stop working show “access token has expired” and can be given a fine-grained token.
  2. Let users create a fine-grained token for each owner they script against.
  3. Optionally forbid creating new classic tokens. Existing ones keep working until they expire.
  4. When no classic token is in use any more (check last used in the central list), switch classic tokens off. You can always switch them on again.

There is no date after which classic tokens disappear by themselves.

Not included yet: permissions finer than the scope categories, listings that include private repositories of the grant, an in-app notification for expiring tokens, and automatic deletion of long-expired tokens.