Specify endpoints to create and delete keys (6e5880b5) · Commits · Fachschaft / Portal

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

+115 −0

Changes for portal/static/docs/api/v0/openapi-spec.yaml: 115 added lines, 0 removed lines.
Original line number	Diff line number	Diff line
		@@ -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