Authentication

All custom proxy endpoints require a valid Forgejo personal access token. The proxy supports three authentication methods.

Method 1: Authorization Header (Preferred)

Pass the token in the Authorization header using the token scheme:

curl -H 'Authorization: token YOUR_FORGEJO_TOKEN' \
  'https://forgejo-proxy.hochguertel.work/api/v1/repos/owner/repo/actions/runs/latest/logs'

This is the recommended approach and matches Forgejo’s own API convention.

Method 2: `access_token` Query Parameter

curl 'https://forgejo-proxy.hochguertel.work/api/v1/repos/owner/repo/actions/runs/latest/logs?access_token=YOUR_FORGEJO_TOKEN'

Method 3: `token` Query Parameter

curl 'https://forgejo-proxy.hochguertel.work/api/v1/repos/owner/repo/actions/runs/latest/logs?token=YOUR_FORGEJO_TOKEN'

Resource-Level Access Control

The proxy enforces access control at the resource level. Before executing a custom endpoint, it verifies that the provided token has read access to the target repository or organisation using Forgejo’s standard API.

This means:

Your token must have at least repository read permission for repo-scoped endpoints
Your token must have at least organisation read permission for org-scoped endpoints
Only after this check passes does the proxy proceed with the requested operation

Per-Request WebUI Credentials

Some proxy endpoints interact with the Forgejo web UI (for example, Projects endpoints that have no REST API). These require the caller to supply Forgejo web credentials via request headers:

Header	Description
`X-Webui-Username`	Your Forgejo username
`X-Webui-Password`	Your Forgejo password

The proxy establishes a per-request session with these credentials — no admin credentials are stored server-side. Each request authenticates independently and the session is discarded after the response is returned.

Security implication: Credentials travel only within the individual HTTP request and are never persisted on the proxy server.

CLI users

The thfg CLI sends these headers automatically when username and password are configured in the host entry (~/.config/thfg/config.json). No manual header management is required.

Direct API callers

curl -H "Authorization: token $YOUR_TOKEN" \
     -H "X-Webui-Username: youruser" \
     -H "X-Webui-Password: yourpassword" \
     https://forgejo-proxy.hochguertel.work/api/v1/repos/org/repo/projects

Generating a Token

Log in to your Forgejo instance
Go to Settings → Applications → Manage Access Tokens
Create a token with at least Repository: Read scope
Copy the token — it is only shown once