Git with a cup of tea, painless self-hosted git service Mirror for internal git.with.parts use https://git.with.parts

3.6 KiB

Raw Blame History

date	title	slug	weight	toc	draft	menu
2018-06-24:00:00+02:00	API Usage	api-usage	40	false	false	[{sidebar [{parent developers} {name API Usage} {weight 40} {identifier api-usage}]}]

API Usage

Table of Contents

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

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 Provider

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.

API Guide:

API Reference guide is auto-generated by swagger and available on: https://gitea.your.host/api/swagger or on gitea demo instance

The OpenAPI document is at: https://gitea.your.host/swagger.v1.json

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":"..."}]

As of v1.8.0 of Gitea, if using basic authentication with the API and your user has two factor authentication enabled, you'll need to send an additional header that contains the one time password (6 digit rotating token). An example of the header is X-Gitea-OTP: 123456 where 123456 is where you'd place the code from your authenticator. Here is how the request would look like in curl:

$ curl -H "X-Gitea-OTP: 123456" --request GET --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens

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.

3.6 KiB Raw Blame History