2.7 KiB

Raw Blame History

date

title

slug

weight

toc

draft

2018-06-24:00:00+02:00

API Usage

api-usage

true

false

sidebar

parent	name	weight	identifier
advanced	API Usage	40	api-usage

Gitea API Usage

Enabling/configuring API access

By default, ENABLE_SWAGGER is true, and MAX_RESPONSE_ITEMS is set to 50. See Config Cheat Sheet for more information.

Authentication via the API

Gitea supports these methods of API authentication:

HTTP basic authentication
token=... parameter in URL query string
access_token=... parameter in URL query string
Authorization: token ... header in HTTP headers

All of these methods accept the same API key token type. You can better understand this by looking at the code -- as of this writing, Gitea parses queries and headers to find the token in modules/auth/auth.go.

You can create an API key token via your Gitea installation's web interface: Settings | Applications | Generate New Token.

OAuth2

Access tokens obtained from Gitea's OAuth2 provider are accepted by these methods:

Authorization bearer ... header in HTTP headers
token=... parameter in URL query string
access_token=... parameter in URL query string

More on the `Authorization:` header

For historical reasons, Gitea needs the word token included before the API key token in an authorization header, like this:

Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675

In a curl command, for instance, this would look like:

curl -X POST "http://localhost:4000/api/v1/repos/test1/test1/issues" \
    -H "accept: application/json" \
    -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
    -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i

As mentioned above, the token used is the same one you would use in the token= string in a GET request.

Listing your issued tokens via the API

As mentioned in #3842, /users/:name/tokens is special and requires you to authenticate using BasicAuth, as follows:

Using basic authentication:

$ curl --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
[{"name":"test","sha1":"..."},{"name":"dev","sha1":"..."}]

Sudo

The API allows admin users to sudo API requests as another user. Simply add either a sudo= parameter or Sudo: request header with the username of the user to sudo.

2.7 KiB Raw Blame History