cerc-io/gitea
16
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rework Token API comments (#15162)

Browse Source 
Move the token API discussion into a common section discussing the
generation and listing of the tokens.  Add a note on the display of
the sha1 during creation and listing.

Co-authored-by: Norwin <noerw@users.noreply.github.com>
This commit is contained in:
Ian Wienand 2021-05-16 23:51:53 +10:00 committed by GitHub
parent 0bf8d34630
commit c3aaf5eafd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 36 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
docs/content/doc/developers/api-usage.en-us.md
View File

@ -40,8 +40,42 @@ 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`.
## 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:
```sh
$ 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.
```sh
$ 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:
```sh
$ 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`.
## OAuth2 Provider
@ -82,26 +116,6 @@ or on
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.