From c8d92447e16a460b9ce3f2d210ca1f5dff75aa24 Mon Sep 17 00:00:00 2001 From: Ian Wienand Date: Fri, 26 Mar 2021 09:25:28 +1100 Subject: [PATCH 1/2] Rework Token API comments 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. --- .../content/doc/developers/api-usage.en-us.md | 58 ++++++++++++------- 1 file changed, 36 insertions(+), 22 deletions(-) diff --git a/docs/content/doc/developers/api-usage.en-us.md b/docs/content/doc/developers/api-usage.en-us.md index 5253cbaa18698..daee7ceba534d 100644 --- a/docs/content/doc/developers/api-usage.en-us.md +++ b/docs/content/doc/developers/api-usage.en-us.md @@ -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//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//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 +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 +``` + +You can also create an API key token via your Gitea installation's web +interface: `Settings | Applications | Generate New Token`. ## OAuth2 Provider @@ -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: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. From 6650476789400b9eccd441decb5e0cd1a3518483 Mon Sep 17 00:00:00 2001 From: 6543 <6543@obermui.de> Date: Sun, 16 May 2021 09:30:28 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Norwin --- docs/content/doc/developers/api-usage.en-us.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/content/doc/developers/api-usage.en-us.md b/docs/content/doc/developers/api-usage.en-us.md index daee7ceba534d..d35253871a874 100644 --- a/docs/content/doc/developers/api-usage.en-us.md +++ b/docs/content/doc/developers/api-usage.en-us.md @@ -63,7 +63,12 @@ $ curl --request GET --url https://yourusername:password@gitea.your.host/api/v1/ [{"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 +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: 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`