mirror of
https://github.com/go-gitea/gitea
synced 2024-12-22 13:14:12 +01:00
2242f381e6
* Added OpenAPI document link to usage The OpenAPI document at /api/swagger.v1.json needs an obvious reference. Sadly, I am English monolingual, so someone else is going to have to do the other languages. In the mean time, this PR should help anyone looking for the file. * Update docs/content/doc/developers/api-usage.en-us.md Co-authored-by: a1012112796 <1012112796@qq.com> Co-authored-by: techknowlogick <matti@mdranta.net> Co-authored-by: a1012112796 <1012112796@qq.com> Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com> Co-authored-by: techknowlogick <techknowlogick@gitea.io>
112 lines
3.6 KiB
Markdown
112 lines
3.6 KiB
Markdown
---
|
|
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"
|
|
---
|
|
|
|
# API Usage
|
|
|
|
**Table of Contents**
|
|
|
|
{{< toc >}}
|
|
|
|
## Enabling/configuring API access
|
|
|
|
By default, `ENABLE_SWAGGER` is true, and
|
|
`MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat
|
|
Sheet](https://docs.gitea.io/en-us/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](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
|
|
|
|
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](https://docs.gitea.io/en-us/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:
|
|
|
|
```sh
|
|
Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
|
|
```
|
|
|
|
In a `curl` command, for instance, this would look like:
|
|
|
|
```sh
|
|
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](https://try.gitea.io/api/swagger)
|
|
|
|
The OpenAPI document is at:
|
|
`https://gitea.your.host/swagger.v1.json`
|
|
|
|
## Listing your issued tokens via the API
|
|
|
|
As mentioned in
|
|
[#3842](https://github.com/go-gitea/gitea/issues/3842#issuecomment-397743346),
|
|
`/users/:name/tokens` is special and requires you to authenticate
|
|
using BasicAuth, as follows:
|
|
|
|
### Using basic authentication:
|
|
|
|
```sh
|
|
$ 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:
|
|
|
|
```sh
|
|
$ 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.
|
|
|
|
## SDKs
|
|
|
|
- [Official go-sdk](https://gitea.com/gitea/go-sdk)
|
|
- [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk)
|