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.

Create an access token

POST
/users/{username}/tokens
curl --request POST \
--url https://gitea.example.com/api/v1/users/example/tokens \
--header 'Authorization: Basic <credentials>' \
--header 'Content-Type: application/json' \
--data '{ "description": "example", "expires_in_days": 1, "justification": "example", "kind": "example", "name": "example", "owner": "example", "repo_selection": "example", "repositories": [ "example" ], "scopes": [ "all", "read:activitypub", "read:issue", "write:misc", "read:notification", "read:organization", "read:package", "read:repository", "read:user" ] }'
username
required
string

Username of the user whose token is to be created

Media typeapplication/json

CreateAccessTokenOption options when create access token

object
description

The description of the token

string
expires_in_days

The lifetime in days, 0 means no expiry. Fine-grained tokens default to 30 days (1-366), classic tokens to no expiry

integer format: int64
justification

Why the token is needed, shown to the approvers of the organization that owns a fine-grained token

string
kind

The kind of token to create: classic (default) or fine_grained

string
name
required
string
owner

The user or organization a fine-grained token is limited to, defaults to the token holder

string
repo_selection

The repository selection of a fine-grained token: public, all or selected

string
repositories

The repositories of a fine-grained token with repo_selection selected, as owner/name

Array<string>
scopes
Array<string>
Example
[
"all",
"read:activitypub",
"read:issue",
"write:misc",
"read:notification",
"read:organization",
"read:package",
"read:repository",
"read:user"
]

AccessToken represents an API access token.

Media typeapplication/json
AccessToken represents an API access token.
object
created_at

The timestamp when the token was created

string format: date-time
description

The description of the token

string
disabled

Whether the token is disabled

boolean
expires_at

The timestamp when the token stops working, absent if it never does

string format: date-time
id

The unique identifier of the access token

integer format: int64
kind

The kind of the token: classic or fine_grained

string
last_used_at

The timestamp when the token was last used

string format: date-time
name

The name of the access token

string
owner

The user or organization a fine-grained token is limited to

string
repo_selection

The repository selection of a fine-grained token: public, all or selected

string
repositories

The selected repositories of a fine-grained token, as owner/name

Array<string>
scopes

The scopes granted to this access token

Array<string>
sha1

The SHA1 hash of the access token

string
token_last_eight

The last eight characters of the token

string
Examplegenerated
{
"created_at": "2026-04-15T12:00:00Z",
"description": "example",
"disabled": true,
"expires_at": "2026-04-15T12:00:00Z",
"id": 1,
"kind": "example",
"last_used_at": "2026-04-15T12:00:00Z",
"name": "example",
"owner": "example",
"repo_selection": "example",
"repositories": [
"example"
],
"scopes": [
"example"
],
"sha1": "example",
"token_last_eight": "example"
}

APIError is error format response

message
string
url
string

APIForbiddenError is a forbidden error response

message
string
url
string