Updated API documentation for the new user-token endpoints

API.md

@@ -7,6 +7,7 @@
 1. [General rules](#general-rules)
 
    - [Authentication](#authentication)
+   - [User token authentication](#user-token-authentication)
    - [Basic requests](#basic-requests)
    - [File uploads](#file-uploads)
    - [Error handling](#error-handling)
@@ -56,6 +57,10 @@
         - [Updating user](#updating-user)
         - [Getting user](#getting-user)
         - [Deleting user](#deleting-user)
+    - User Tokens
+        - [Listing tokens](#listing-tokens)
+        - [Creating token](#creating-token)
+        - [Deleting token](#deleting-token)
     - Password reset
         - [Password reset - step 1: mail request](#password-reset---step-2-confirmation)
         - [Password reset - step 2: confirmation](#password-reset---step-2-confirmation)
@@ -70,6 +75,7 @@
 
    - [User](#user)
    - [Micro user](#micro-user)
+   - [User token](#user-token)
    - [Tag category](#tag-category)
    - [Tag](#tag)
    - [Micro tag](#micro-tag)
@@ -91,16 +97,35 @@
 ## Authentication
 
 Authentication is achieved by means of [basic HTTP
-auth](https://en.wikipedia.org/wiki/Basic_access_authentication). For this
-reason, it is recommended to connect through HTTPS. There are no sessions, so
-every privileged request must be authenticated. Available privileges depend on
-the user's rank. The way how rank translates to privileges is defined in the
-server's configuration.
+auth](https://en.wikipedia.org/wiki/Basic_access_authentication) or through the 
+use of [user token authentication](#user-token-authentication). For this reason, 
+it is recommended to connect through HTTPS. There are no sessions, so every 
+privileged request must be authenticated. Available privileges depend on the 
+user's rank. The way how rank translates to privileges is defined in the server's 
+configuration.
 
 It is recommended to add `?bump-login` GET parameter to the first request in a
 client "session" (where the definition of a session is up to the client), so
 that the user's last login time is kept up to date.
 
+## User token authentication
+
+User token authentication works similarly to [basic HTTP 
+auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Because it
+operates similarly to ***basic HTTP auth*** it is still recommended to connect
+through HTTPS. The authorization header uses the type of Token and the username
+and token are encoded as Base64 and sent as the second parameter.
+
+Example header for user1:token-is-more-secure
+```
+Authorization: Token dXNlcjE6dG9rZW4taXMtbW9yZS1zZWN1cmU=
+```
+
+The benefit of token authentication is that beyond the initial login to acquire
+the first token, there is no need to transmit the user password in plaintext via
+basic auth. Additionally tokens can be revoked at anytime allowing a cleaner 
+interface for isolating clients from user credentials.
+
 ## Basic requests
 
 Every request must use `Content-Type: application/json` and `Accept:
@@ -1469,6 +1494,74 @@ data.
 
     Deletes existing user.
 
+## Listing tokens
+- **Request**
+
+    `GET /user-tokens/`
+
+- **Output**
+
+    An [unpaged search result resource](#unpaged-search-result), for which
+    `<resource>` is a [user token resource](#user-token).
+
+- **Errors**
+
+    - privileges are too low
+
+- **Description**
+
+    Searches for users tokens for the currently logged in user.
+
+## Creating token
+- **Request**
+
+    `POST /user-token`
+
+- **Input**
+
+    ```json5
+    {}
+    ```
+
+- **Output**
+
+    A [user token resource](#user-token).
+
+- **Errors**
+
+    - privileges are too low
+
+- **Description**
+
+    Creates a new user token that can be used for authentication of api
+    endpoints instead of a password.
+
+## Deleting token
+- **Request**
+
+    `DELETE /user-token/<token>`
+
+- **Input**
+
+    ```json5
+    {}
+    ```
+
+- **Output**
+
+    ```json5
+    {}
+    ```
+
+- **Errors**
+
+    - the token does not exist
+    - privileges are too low
+
+- **Description**
+
+    Deletes existing user token.
+
 ## Password reset - step 1: mail request
 - **Request**
 
@@ -1701,6 +1794,30 @@ A single user.
 
 A [user resource](#user) stripped down to `name` and `avatarUrl` fields.
 
+## User token
+**Description**
+
+A single user token.
+
+**Structure**
+
+```json5
+{
+    "user":         <user>,
+    "token":        <token>,
+    "enabled":      <enabled>,
+    "creationTime": <creation-time>,
+    "lastEditTime": <last-edit-time>,
+}
+```
+
+**Field meaning**
+- `<user>`: micro user. See [micro user](#micro-user).
+- `<token>`: the token that can be used to authenticate the user.
+- `<enabled>`: whether the token is still valid for authentication.
+- `<creation-time>`: time the user token was created , formatted as per RFC 3339.
+- `<last-edit-time>`: time the user token was edited, formatted as per RFC 3339.
+
 ## Tag category
 **Description**
 

server/szurubooru/api/user_token_api.py

@@ -17,7 +17,7 @@ def get_user_tokens(ctx: rest.Context, _params: Dict[str, str] = {}) -> rest.Res
     auth.verify_privilege(ctx.user, 'user_token:list')
     user_token_list = user_tokens.get_user_tokens(ctx.user)
     return {
-        "tokens": [_serialize(ctx, token) for token in user_token_list]
+        "results": [_serialize(ctx, token) for token in user_token_list]
     }