Authentication

Overview

Gitea API supports multiple authentication methods to secure access to your resources. The recommended method is using personal access tokens with the Authorization header.

Authentication Methods

Gitea supports the following authentication methods:

Authorization Header Token (Recommended)
HTTP Basic Authentication
OAuth2
Query Parameters (Deprecated)

Personal Access Tokens

Creating a Token

Personal access tokens are the recommended way to authenticate with the Gitea API.

Log in to your Gitea instance
Navigate to Settings → Applications → Access Tokens
Click Generate New Token
Enter a token name and select the required scopes
Click Generate Token
Copy the token immediately (it won’t be shown again)

Store your access tokens securely. They provide the same level of access as your password for the scopes you’ve granted.

Using Tokens in Requests

The recommended way to use tokens is via the Authorization header with the token prefix:

curl -H "Authorization: token YOUR_TOKEN" \
  https://your-gitea-instance.com/api/v1/user

Token Scopes

Tokens can be created with specific scopes to limit their permissions:

Scope Category	Read	Write	Description
`repo`	`read:repository`	`write:repository`	Access to repositories
`admin:org`	`read:organization`	`write:organization`	Organization management
`admin:public_key`	`read:public_key`	`write:public_key`	SSH key management
`admin:repo_hook`	`read:repo_hook`	`write:repo_hook`	Repository webhooks
`admin:org_hook`	-	`write:org_hook`	Organization webhooks
`admin:user_hook`	-	`write:user_hook`	User webhooks
`notification`	`read:notification`	`write:notification`	Notifications
`user`	`read:user`	`write:user`	User information
`admin:gpg_key`	`read:gpg_key`	`write:gpg_key`	GPG key management
`admin:application`	`read:application`	`write:application`	OAuth2 applications
`package`	`read:package`	`write:package`	Package registry
`admin:misc`	-	`write:misc`	Miscellaneous admin
`activitypub`	`read:activitypub`	`write:activitypub`	ActivityPub federation

The API automatically determines the required access level (read/write) based on the HTTP method. GET requests require read access, while POST/PUT/PATCH/DELETE require write access.

Public-Only Scopes

Tokens can be restricted to public resources only by appending :public to the scope:

read:repository:public - Only access public repositories
read:organization:public - Only access public organizations
read:user:public - Only access public user information

HTTP Basic Authentication

Basic authentication uses your Gitea username and password (or token).

curl -u username:password \
  https://your-gitea-instance.com/api/v1/user

HTTP Basic Authentication is supported but not recommended for API usage. Use personal access tokens with the Authorization header instead.

Two-Factor Authentication (2FA)

If two-factor authentication is enabled on your account, include the TOTP code in the X-GITEA-OTP header:

curl -u username:password \
  -H "X-GITEA-OTP: 123456" \
  https://your-gitea-instance.com/api/v1/user

OAuth2 Authentication

Gitea supports OAuth2 for third-party application authentication.

Creating an OAuth2 Application

Go to Settings → Applications → OAuth2 Applications
Click Create a new OAuth2 Application
Enter application details and redirect URI
Note the Client ID and Client Secret

OAuth2 Flow

Authorization Request:

GET https://your-gitea-instance.com/login/oauth/authorize?
  client_id=CLIENT_ID&
  redirect_uri=REDIRECT_URI&
  response_type=code&
  state=RANDOM_STATE

Token Exchange:

curl -X POST https://your-gitea-instance.com/login/oauth/access_token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "grant_type": "authorization_code",
    "redirect_uri": "REDIRECT_URI"
  }'

Use Access Token:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://your-gitea-instance.com/api/v1/user

OAuth2 tokens are JWT (JSON Web Tokens) and contain a dot (.) in the token string.

Query Parameter Authentication (Deprecated)

Query parameter authentication is deprecated and will be removed in Gitea 1.23. Migrate to Authorization header authentication.

Historically, tokens could be passed as query parameters:

# Using 'token' parameter (deprecated)
curl https://your-gitea-instance.com/api/v1/user?token=YOUR_TOKEN

# Using 'access_token' parameter (deprecated)
curl https://your-gitea-instance.com/api/v1/user?access_token=YOUR_TOKEN

If query parameter authentication is disabled via DISABLE_QUERY_AUTH_TOKEN=true, these requests will fail with a warning in the server logs.

Sudo / Impersonation

Administrators can perform API requests on behalf of other users using the sudo feature.

Using Sudo Header

curl -H "Authorization: token ADMIN_TOKEN" \
  -H "Sudo: target-username" \
  https://your-gitea-instance.com/api/v1/user

Using Sudo Query Parameter

curl -H "Authorization: token ADMIN_TOKEN" \
  "https://your-gitea-instance.com/api/v1/user?sudo=target-username"

Sudo functionality requires administrator privileges. Non-admin users will receive a 403 Forbidden error.

Actions Authentication

Gitea Actions workflows can authenticate using automatic task tokens:

steps:
  - name: Call API
    run: |
      curl -H "Authorization: Bearer ${{ secrets.ACTIONS_RUNTIME_TOKEN }}" \
        https://your-gitea-instance.com/api/v1/repos/${{ github.repository }}

Task tokens are:

Automatically generated for running workflows
Scoped to the repository where the action is running
Valid only while the task is in “running” status

Testing Authentication

Test your authentication by retrieving your user information:

curl -H "Authorization: token YOUR_TOKEN" \
  https://your-gitea-instance.com/api/v1/user

Security Best Practices

Use HTTPS

Always use HTTPS in production to prevent token interception

Scope Tokens

Grant minimal necessary scopes to access tokens

Rotate Tokens

Regularly rotate tokens and revoke unused ones

Secure Storage

Never commit tokens to version control or expose in logs

Managing Tokens via API

You can manage access tokens programmatically:

List Tokens

curl -u username:password \
  https://your-gitea-instance.com/api/v1/users/username/tokens

Create Token

curl -u username:password \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"name":"my-token","scopes":["read:repository","write:repository"]}' \
  https://your-gitea-instance.com/api/v1/users/username/tokens

Delete Token

curl -u username:password \
  -X DELETE \
  https://your-gitea-instance.com/api/v1/users/username/tokens/TOKEN_ID

Creating and deleting tokens requires Basic Authentication or Reverse Proxy authentication. You cannot use a token to create another token.

Troubleshooting

401 Unauthorized

Verify the token is correct and not expired
Check that the token hasn’t been revoked
Ensure you’re using the correct authentication method

403 Forbidden

Verify the token has the required scopes
Check if the account is active and not prohibited from login
Ensure 2FA requirements are met if enforced
For sudo requests, verify admin privileges

Deprecation Warnings

If you see X-Gitea-Warning headers about deprecated authentication:

X-Gitea-Warning: token and access_token API authentication is deprecated

Migrate to using the Authorization header:

# Instead of:
curl "https://your-gitea-instance.com/api/v1/user?token=YOUR_TOKEN"

# Use:
curl -H "Authorization: token YOUR_TOKEN" \
  https://your-gitea-instance.com/api/v1/user

Overview

Repositories

Issues & Pull Requests

Organizations & Teams

Users

Actions & Packages

​Overview

​Authentication Methods

​Personal Access Tokens

​Creating a Token

​Using Tokens in Requests

​Token Scopes

​Public-Only Scopes

​HTTP Basic Authentication

​Two-Factor Authentication (2FA)

​OAuth2 Authentication

​Creating an OAuth2 Application

​OAuth2 Flow

​Query Parameter Authentication (Deprecated)

​Sudo / Impersonation

​Using Sudo Header

​Using Sudo Query Parameter

​Actions Authentication

​Testing Authentication

​Security Best Practices

Use HTTPS

Scope Tokens

Rotate Tokens

Secure Storage

​Managing Tokens via API

​List Tokens

​Create Token

​Delete Token

​Troubleshooting

​401 Unauthorized

​403 Forbidden

​Deprecation Warnings

​Next Steps

API Reference

Webhooks

Build docs developers (and LLMs) love

Overview

Authentication Methods

Personal Access Tokens

Creating a Token

Using Tokens in Requests

Token Scopes

Public-Only Scopes

HTTP Basic Authentication

Two-Factor Authentication (2FA)

OAuth2 Authentication

Creating an OAuth2 Application

OAuth2 Flow

Query Parameter Authentication (Deprecated)

Sudo / Impersonation

Using Sudo Header

Using Sudo Query Parameter

Actions Authentication

Testing Authentication

Security Best Practices

Managing Tokens via API

List Tokens

Create Token

Delete Token

Troubleshooting

401 Unauthorized

403 Forbidden

Deprecation Warnings

Next Steps