Specify endpoints to create and delete keys

portal/static/docs/api/v0/openapi-spec.yaml

@@ -29,6 +29,59 @@ paths:
             description:
                 Get the (singleton) `ApplicationVersion` instance describing the
                 version of this app.
+    /keys:
+        summary: Path used to manage the list of keys (effectively only there to create one).
+        description: ""
+        post:
+            requestBody:
+                content: {}
+                required: true
+            responses:
+                "201":
+                    description: A key has been created (i.e. the presented credentials were accepted)
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/Key"
+                "401":
+                    $ref: "#/components/responses/UnauthorizedError"
+            security:
+                - userPasswordAuth: []
+            operationId: createKey
+            summary: Create a key
+            description: |-
+                Create a new key whose secret can be used to authenticate against all endpoints requiring `secretBearerAuth`.
+
+                Of course you have to be authenticated to get such a key because we don't want to allow arbitrary persons to use protected endpoints.
+                Therefore, this endpoint itself also requires authentication, however, not with `secretBearerAuth` (because where would you get that
+                secret from) but with `userPasswordAuth` (i.e. with username and password).
+
+                The body of the `POST` request is empty, because the server will generate all fields of the key.
+    /keys/{uuid}:
+        summary: Path used to manage a single key (effectively only there to delete one).
+        delete:
+            responses:
+                "204":
+                    description: The key was successfully deleted (= revoked).
+                "401":
+                    $ref: "#/components/responses/UnauthorizedError"
+                "404":
+                    description: No such key exists (or at least none that can be deleted by the current user).
+            operationId: deleteKey
+            summary: Delete a key
+            description: |-
+                Delete (= revoke) a key. This means the secret can no longer be used to authenticate when `secretBearerAuth` is required.
+
+                Authentication is required to revoke a key.
+            security:
+                - secretBearerAuth: []
+        parameters:
+            - name: uuid
+              description: The unique identifier of the key.
+              schema:
+                  type: string
+              in: path
+              required: true
 components:
     schemas:
         ApplicationVersion:
@@ -72,3 +125,65 @@ components:
                 commit: 9988d805651ce7d553ac8556eb52692953a19db5
                 datetime: 2023-01-16T08:21:29+00:00
                 isDevelop: false
+        Key:
+            title: Key
+            description:
+                A key to authenticate against the API. It consists of a uuid (used to manage the key) and a secret (which actually authenticates the user).
+            required:
+                - secret
+                - uuid
+                - createdAt
+                - expiresAt
+                - userUuid
+            type: object
+            properties:
+                uuid:
+                    description: A uuid to identify the key (which can be later used to delete it).
+                    type: string
+                    readOnly: true
+                secret:
+                    description:
+                        A token that can be used as secret to authenticate against
+                        the API.
+                    type: string
+                    readOnly: true
+                createdAt:
+                    description: The zoned date and time this key was created at.
+                    type: string
+                    format: date-time
+                    readOnly: true
+                expiresAt:
+                    description: The zoned date and time this key expires at, i.e. after which it cannot be used anymore.
+                    type: string
+                    format: date-time
+                    readOnly: true
+                userUuid:
+                    description: The uuid of the user who created the key.
+                    type: string
+                    readOnly: true
+            example:
+                uuid: 2ce9dd96-fef2-4f9d-b3d4-2ab7ea9c11f6
+                secret: portal.3CbapNRIF2biIY1B0lHy-CVu18xIu3X2YIvzZeWzE8A
+                createdAt: "2023-04-16T18:36:23+00:00"
+                expiresAt: "2023-04-16T19:36:23+00:00"
+                userUuid: 75e9ec37-54ff-4da3-b5cb-68e1870be3c0
+    responses:
+        UnauthorizedError:
+            description: |-
+                Unauthorized to execute operation, because the session could not be authenticated, because either no authentication was provided or the provided authentication was invalid.
+        NotFoundError:
+            description: |-
+                The specified resource (i.e., object) could not be found. This can be because it truly doesn't exist (the more likely case), or because the client is not allowed to know the resource exists (e.g., because it is private and belongs to another user).
+        BadRequestError:
+            description: |-
+                The request body was invalid, because it is syntactically or semantically malformed. The error response by the server might provide more details.
+    securitySchemes:
+        secretBearerAuth:
+            scheme: bearer
+            bearerFormat: Random string
+            type: http
+            description: Authentication against endpoints with a secret using HTTP Bearer Auth
+        userPasswordAuth:
+            scheme: basic
+            type: http
+            description: Authentication against endpoints with a username and password using HTTP Basic Auth