github-mirror/gitea
2
0
Fork 0
mirror of https://github.com/go-gitea/gitea.git synced 2024-12-01 14:25:11 +08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
ab0e588217
gitea/docs/content/development/api-usage.en-us.md
John Olheiser bd4c7ce578
Docusaurus-ify (#26051) 
This PR cleans up the docs in a way to make them simpler to ingest by
our [docs repo](https://gitea.com/gitea/gitea-docusaurus).

1. It includes all of the sed invocations our ingestion did, removing
the need to do it at build time.
2. It replaces the shortcode variable replacement method with
`@variable@` style, simply for easier sed invocations when required.
3. It removes unused files and moves the docs up a level as cleanup.

---------

Signed-off-by: jolheiser <john.olheiser@gmail.com>
2023-07-26 04:53:13 +00:00

4.6 KiB
Raw Blame History

date title slug sidebar_position toc draft aliases menu
2018-06-24:00:00+02:00 API Usage api-usage 40 false false
/en-us/api-usage
sidebar
parent name sidebar_position identifier
development API Usage 40 api-usage

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

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.

Generating and listing API tokens

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 -H "Content-Type: application/json" -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 --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" --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.

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 "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.

Pagination

The API supports pagination. The page and limit parameters are used to specify the page number and the number of items per page. As well, the Link header is returned with the next, previous, and last page links if there are more than one pages. The x-total-count is also returned to indicate the total number of items.

curl -v "http://localhost/api/v1/repos/search?limit=1"
...
< link: <http://localhost/api/v1/repos/search?limit=1&page=2>; rel="next",<http://localhost/api/v1/repos/search?limit=1&page=5252>; rel="last"
...
< x-total-count: 5252

API Guide

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

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.

SDKs