gitea/docs/content/doc/advanced/api-usage.en-us.md
stevegt aaf6be3ee6 Create api-usage doc page (#4306)
* add api user guides in doc

* update user-guides api page

* fix typo: user guides -> user guide

* move api-usage page under advanced category

* flesh out API usage docs

* Build on work by @tungsheng

* Address issues raised in #4037, #3673, and #4243

* Close #4247

Signed-off-by: Steve Traugott <stevegt@t7a.org>
2018-06-25 20:12:46 +08:00

2.2 KiB

date title slug weight toc draft menu
2018-06-24:00:00+02:00 API Usage api-usage 40 true false
sidebar
parent name weight identifier
advanced API Usage 40 api-usage

Gitea API Usage

Enabling/configuring API access

By default, ENABLE_SWAGGER_ENDPOINT 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 apiKey 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 apiKey token via your gitea install's web interface: Settings | Applications | Generate New Token.

More on the Authorization: header

For historical reasons, Gitea needs the word token included before the apiKey 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":"..."}]