summaryrefslogtreecommitdiffstats
path: root/documentation/api/collections.md
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/api/collections.md')
-rw-r--r--documentation/api/collections.md168
1 files changed, 168 insertions, 0 deletions
diff --git a/documentation/api/collections.md b/documentation/api/collections.md
new file mode 100644
index 0000000..301a0bb
--- /dev/null
+++ b/documentation/api/collections.md
@@ -0,0 +1,168 @@
+# Collections
+Collections can be called with the api url append with the resource name.
+```
+https://<domain_bss>/api/<collection>/<resource>
+```
+```
+https://<domain_bas>/api/<collection>/:id/<resource>
+```
+
+## Authentication
+The authentication handles the authentication processes like the initial setup, login and logout methods.
+```
+https://<domain_bas>/api/authentication/
+```
+
+### Token Login
+Login method to get a json web token (jwt) for the Authorization header, to make authenticated api calls.
+
+**Request**
+```json
+POST Request - unauthorized
+https://<domain_bas>/api/authentication/token
+
+POST Body
+{
+ "username": "<username>",
+ "password": "<password>"
+}
+```
+
+> **\<username\>**\* - Login name of the user's account.\
+> **\<password\>**\* - Corresponding password to the user's account.\
+> \* Required
+
+**Response**
+* **200 - OK**
+```json
+{
+ "token": "<token>"
+}
+```
+
+> **\<token\>** - Json web token (jwt)
+
+* **400 - Bad Request**
+ * INVALID\_USERNAME - Username does not fullfill the requirements. (No whitespaces)
+ * PASSWORD\_MISSING - This services requires a password.
+ * USER\_MISSING - This service requires an username.
+* **401 - Unauthorized**
+ * PASSWORD\_INVALID - The provided password is invalid.
+* **404 - Not Found**
+ * USER\_NOTFOUND - User does not exist.
+* **500 - Internal Server Error**
+ * DATABASE\_HASH\_INVALID - The hash in the database is corrupted.
+ * INVALID\_UNRECOGNIZED\_HASH - This hash was not made with secure-password. Attempt legacy algorithm.
+ * JWT\_ERROR - Jwt sign failed.
+ * PASSWORD\_REHASH\_ERROR - Rehashing the password failed.
+ * PASSWORD\_VERIFY\_ERROR - Verifying the password failed.
+
+### Cookie Login
+Login method which sets the *jwt_hp* and *jwt_s* cookie.
+
+**Request**
+```json
+POST Request - unauthorized
+https://<domain_bas>/api/authentication/cookies
+
+POST Body
+{
+ "username": "<username>",
+ "password": "<password>"
+}
+```
+
+> **\<username\>**\* - Login name of the user's account.\
+> **\<password\>**\* - Corresponding password to the user's account.\
+> \* Required
+
+**Response**
+* **200 - OK**
+
+| Name | Value | httpOnly | secure |
+| ------- | ------------------------ |:---------:|:------:|
+| jwt\_hp | <token\_header\_payload> | false | true |
+| jwt\_s | <token\_signature> | true | true |
+
+
+
+### Logout
+Deletes the cookies *jwt_hp* and *jwt_s* from the client.
+
+**Request**
+```json
+POST Request - unauthorized
+https://<domain_bas>/api/authentication/logout
+```
+
+**Response**
+* **200 - OK**
+
+## Setup
+### Status
+Returns wheather the unauthorized user (root account) creation can be executed.
+
+**Request**
+```
+GET-Request - unauthorized
+https://<domain_bas>/api/status
+```
+
+**Response**
+* **200 - OK**
+* **403 - Forbidden**
+ * USERTABLE\_NOT\_EMPTY - The user table is not empty, unauthorized creation is forbidden.
+
+### Create Root Account
+Creates the initial root account with superadmin priviliges.\
+This request is only permitted when the user table is empty.
+
+**Request**
+```json
+POST Request - unauthorized
+https://<domain_bas>/api/setup
+
+body {
+ "username": "<username>",
+ "password": "<password>",
+ "name": "<name>",
+ "email": "<email>"
+}
+```
+
+> **\<username\>**\* - Login name of the user's account.\
+> **\<password\>**\* - Corresponding password to the user's account.\
+> **\<name\>** - Full name of the user.\
+> **\<email\>** - Email of the user.\
+> \* Required
+
+**Response**
+* **200 - OK**
+* **400 - Bad Request**
+ * INVALID\_USERNAME - Username does not fullfill the requirements. (No whitespaces)
+ * PASSWORD\_MISSING - This services requires a password.
+ * PASSWORD\_REQUIREMENTS - The password requirements are not fullfilled.
+ * USER\_MISSING - This service requires an username.
+* **401 - Unauthorized**
+ * PASSWORD\_INVALID - The provided password is invalid.
+* **403 - Forbidden**
+ * USERTABLE\_NOT\_EMPTY - The user table is not empty, unauthorized creation is forbidden.
+* **500 - Internal Server Error**
+ * DATABASE\_HASH\_INVALID - The hash in the database is corrupted.
+ * INVALID\_UNRECOGNIZED\_HASH - This hash was not made with secure-password. Attempt legacy algorithm.
+ * PASSWORD\_HASH\_ERROR - Hashing the password failed.
+ * PASSWORD\_REHASH\_ERROR - Rehashing the password failed.
+ * PASSWORD\_VERIFY\_ERROR - Verifying the password failed.
+ * USER\_ALREADY\_EXISTS - The provided username already exists.
+ * USER\_CREATE\_ERROR - User could not be created.
+
+## Backends
+## Backend Types
+## Clients
+## Configloader
+## Configuratior
+## Groups
+## Ipxe
+## Permissions
+## Roles
+## Users \ No newline at end of file