Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rework Token API comments #15162

Merged
merged 3 commits into from
May 16, 2021
Merged

Rework Token API comments #15162

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c8d9244
Rework Token API comments
ianw Mar 25, 2021
6650476
Apply suggestions from code review
6543 May 16, 2021
1a40351
Merge branch 'main' into token-api-doc
6543 May 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 36 additions & 22 deletions docs/content/doc/developers/api-usage.en-us.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:[email protected]/api/v1/users/<username>/tokens
[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
```

As of v1.8.0 of Gitea, if using basic authentication with the API and
6543 marked this conversation as resolved.
Show resolved Hide resolved
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:[email protected]/api/v1/users/yourusername/tokens
```

You can also create an API key token via your Gitea installation's web
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd put this first in this section as it is very short, and doesn't get lost in the API noise ;)

interface: `Settings | Applications | Generate New Token`.

## OAuth2 Provider

Expand Down Expand Up @@ -79,26 +113,6 @@ API Reference guide is auto-generated by swagger and available on:
or on
[gitea demo instance](https://try.gitea.io/api/swagger)

## 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:[email protected]/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:[email protected]/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.
Expand Down