From dc102d24f0fcb6247388880abc7f3208d0b7a9eb Mon Sep 17 00:00:00 2001 From: Jannik Schönartz Date: Sun, 10 Mar 2019 03:50:32 +0000 Subject: [documentation] Add documentation site Override css (Design the topbar & site) <-- A lot of Udo's help Create structure for the differen pages Start writing the installation Write the getting started API site Write documentation of the authentication api Write documentation of the setup api --- documentation/api/collections.md | 168 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 documentation/api/collections.md (limited to 'documentation/api/collections.md') 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:///api// +``` +``` +https:///api//:id/ +``` + +## Authentication +The authentication handles the authentication processes like the initial setup, login and logout methods. +``` +https:///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:///api/authentication/token + +POST Body +{ + "username": "", + "password": "" +} +``` + +> **\**\* - Login name of the user's account.\ +> **\**\* - Corresponding password to the user's account.\ +> \* Required + +**Response** +* **200 - OK** +```json +{ + "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:///api/authentication/cookies + +POST Body +{ + "username": "", + "password": "" +} +``` + +> **\**\* - Login name of the user's account.\ +> **\**\* - Corresponding password to the user's account.\ +> \* Required + +**Response** +* **200 - OK** + +| Name | Value | httpOnly | secure | +| ------- | ------------------------ |:---------:|:------:| +| jwt\_hp | | false | true | +| jwt\_s | | true | true | + + + +### Logout +Deletes the cookies *jwt_hp* and *jwt_s* from the client. + +**Request** +```json +POST Request - unauthorized +https:///api/authentication/logout +``` + +**Response** +* **200 - OK** + +## Setup +### Status +Returns wheather the unauthorized user (root account) creation can be executed. + +**Request** +``` +GET-Request - unauthorized +https:///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:///api/setup + +body { + "username": "", + "password": "", + "name": "", + "email": "" +} +``` + +> **\**\* - Login name of the user's account.\ +> **\**\* - Corresponding password to the user's account.\ +> **\** - Full name of the user.\ +> **\** - 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 -- cgit v1.2.3-55-g7522