forgejo-federation/docs/content/doc/advanced/api-usage.en-us.md
Jonas Franz 79ce24bc6f
Add oauth2 documentation (#6604)
* Add oauth2 documentation

Signed-off-by: Jonas Franz <info@jonasfranz.software>

* Apply suggestions from code review

Co-Authored-By: jonasfranz <info@jonasfranz.software>

* Update docs/content/doc/advanced/oauth2-provider.md

Co-Authored-By: jonasfranz <info@jonasfranz.software>

* Update oauth2-provider.md
2019-04-14 10:42:11 +02:00

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