Authentication

Learn how to authenticate with the Gitea API using tokens, basic auth, and OAuth2

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:

1. Authorization Header Token (Recommended)
2. HTTP Basic Authentication
3. OAuth2
4. Query Parameters (Deprecated)

Personal Access Tokens

Creating a Token

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

1. Log in to your Gitea instance
2. Navigate to Settings → Applications → Access Tokens
3. Click Generate New Token
4. Enter a token name and select the required scopes
5. Click Generate Token
6. 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

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

fetch('https://your-gitea-instance.com/api/v1/user', {
  headers: {
    'Authorization': 'token YOUR_TOKEN'
  }
})
.then(response => response.json())
.then(data => console.log(data));

import requests

headers = {
    'Authorization': 'token YOUR_TOKEN'
}

response = requests.get(
    'https://your-gitea-instance.com/api/v1/user',
    headers=headers
)
print(response.json())

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://your-gitea-instance.com/api/v1/user", nil)
    req.Header.Add("Authorization", "token YOUR_TOKEN")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
    
    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

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).

Username and Password

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

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

curl -u YOUR_TOKEN:x-oauth-basic \
  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

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

OAuth2 Flow

1. 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

2. 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"
  }'

3. 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:

Test Token

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

{
  "id": 1,
  "login": "username",
  "email": "[e-mail]",
  "full_name": "User Name",
  "avatar_url": "https://your-gitea-instance.com/avatars/1"
}

{
  "message": "token is required"
}

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

Next Steps

API Reference

Explore available API endpoints

Webhooks

Set up webhooks for event notifications