From 953989cd7e19c2c6c215ba22b57f136019de43e7 Mon Sep 17 00:00:00 2001 From: julianfoad Date: Thu, 14 Nov 2024 16:31:21 +0000 Subject: [PATCH] docs: api-usage: tokens need 'scopes' Document the "scopes" field that is now required when generating API tokens. Refer to the documentation of scope names. Signed-off-by: julianfoad --- docs/user/api-usage.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/user/api-usage.md b/docs/user/api-usage.md index ec7bcc5d..7c8d4d37 100644 --- a/docs/user/api-usage.md +++ b/docs/user/api-usage.md @@ -33,10 +33,12 @@ Note that `/users/:name/tokens` is a special endpoint and requires you to authenticate using `BasicAuth` and a password, as follows: ```sh -$ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:password https://forgejo.your.host/api/v1/users//tokens -{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"} +$ curl -H "Content-Type: application/json" -d '{"name":"test","scopes":["write:package"]}' -u username:password https://forgejo.your.host/api/v1/users//tokens +{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d","scopes":["write:package"]} ``` +The keys of the JSON data object are `name` (the display name for the token) and `scopes` (list of [Access Token scope](../token-scope/) names). + 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.