update api docs

.changeset/allow_for_bypassing_basic_auth_using_a_renterd_auth_cookie.md

@@ -3,3 +3,8 @@ default: minor
 ---
 
 # Allow for bypassing basic auth using a 'renterd_auth' cookie
+
+Added a new `POST /auth` endpoint with a single required parameter 'validity'
+(ms) which creates a new renterd auth token. The client can set that token as
+the value of the 'renterd_auth' cookie to bypass basic auth for the duration of
+the token's validity.

internal/utils/web.go

@@ -95,24 +95,30 @@ func Auth(password string) func(http.Handler) http.Handler {
 
 func AuthHandler(password string) http.Handler {
 	return jape.BasicAuth(password)(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
-		w.Header().Set("Content-Type", "text/plain")
+		if req.Method != http.MethodPost {
+			w.WriteHeader(http.StatusMethodNotAllowed)
+			return // only POST is allowed
+		}
 
 		// parse validity
 		validityMS := req.FormValue("validity")
 		if validityMS == "" {
+			w.Header().Set("Content-Type", "text/plain")
 			w.WriteHeader(http.StatusBadRequest)
 			w.Write([]byte("'validity' parameter is missing"))
 			return
 		}
 		var validity time.Duration
 		if _, err := fmt.Sscan(validityMS, &validity); err != nil {
+			w.Header().Set("Content-Type", "text/plain")
 			w.WriteHeader(http.StatusBadRequest)
 			w.Write([]byte("failed to parse validity"))
 			return
 		}
 		validity *= time.Millisecond
 
 		// send token
+		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusOK)
 		w.Write([]byte(fmt.Sprintf(`{"token": %q}`, authTokens.GenerateNew(validity))))
 	}))

openapi.yml

@@ -13,6 +13,35 @@ tags:
     description: Bus operations and management
 
 paths:
+  /auth:
+    post:
+      tags:
+        - authentication
+      summary: Create a new authentication token to use with the 'renterd_auth' cookie
+      description: Creates a new authentication token with the specified 'validity' duration. The token can be attached to a request as the `renterd_auth` cookie as an alternative way to Basic Auth for the API.`
+      parameters:
+        - name: validity
+          description: The duration in milliseconds for which the token will be valid
+          example: 10000
+          in: query
+          required: true
+          schema:
+            type: integer
+            format: int64
+      responses:
+        "200":
+          description: Successfully created a new token
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token:
+                    type: string
+                    pattern: "^[a-fA-F0-9]{32}$"
+                    description: A hex-encoded string representing the token
+        "400":
+          description: Bad request
   #############################
   #
   # Autopilot routes