date: “2018-06-24:00:00+02:00” title: “API Usage” slug: “api-usage” weight: 40 toc: false draft: false menu: sidebar:
parent: "developers"
name: "API Usage"
weight: 40
identifier: "api-usage"
Table of Contents
{{< toc >}}
By default, ENABLE_SWAGGER
is true, and
MAX_RESPONSE_ITEMS
is set to 50. See Config Cheat
Sheet for more
information.
Gitea supports these methods of API authentication:
token=...
parameter in URL query stringaccess_token=...
parameter in URL query stringAuthorization: token ...
header in HTTP headersAll 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.
A new token can be generated with a POST
request to
/users/:name/tokens
.
Note that /users/:name/tokens
is a special endpoint and requires you
to authenticate using BasicAuth
and a password, as follows:
$ curl -XPOST -H "Content-Type: application/json" -k -d '{"name":"test"}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
The sha1
(the token) is only returned once and is not stored in
plain-text. It will not be displayed when listing tokens with a GET
request; e.g.
$ curl --request GET --url https://yourusername:password@gitea.your.host/api/v1/users/<username>/tokens
[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
To use the API with basic authentication with two factor authentication
enabled, you’ll need to send an additional header that contains the one
time password (6 digitrotating 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
You can also create an API key token via your Gitea installation’s web
interface: Settings | Applications | Generate New Token
.
Access tokens obtained from Gitea’s OAuth2 provider are accepted by these methods:
Authorization bearer ...
header in HTTP headerstoken=...
parameter in URL query stringaccess_token=...
parameter in URL query stringAuthorization:
headerFor 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 Reference guide is auto-generated by swagger and available on:
https://gitea.your.host/api/swagger
or on the
Gitea demo instance
The OpenAPI document is at:
https://gitea.your.host/swagger.v1.json
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.