Add basically API documentation

docs/api/auth.md

@@ -0,0 +1,86 @@
+# /auth
+
+This endpoint is for the user authentication.
+
+For this, mail addresses are used. The user starts
+a authentication flow by sending the mail address.
+Then the caller gets a mail login token and a
+code is sent to the specified mail address.
+After this, the caller can send the mail login token
+and the code received by mail to get a mail auth token which can be
+used at other APIs for creating a family, signing in into an existing family or
+recovering a password.
+
+## POST /auth/send-mail-login-code-v2
+
+Use this to start authenticating.
+
+### Request
+
+see [this JSON schema](../schema/sendmaillogincoderequest.md)
+
+#### example request
+
+```
+{
+  "mail": "test@timelimit.io",
+  "locale": "de"
+}
+```
+
+### Response
+
+If the request body is malformed or the mail address is invalid: HTTP status code 400 Bad Request
+
+If the rate limit was exceeded: HTTP status code 429 Too Many Requests
+
+If a whitelist was configured and the mail address is not within it: ``{"mailAddressNotWhitelisted": true}``
+
+If a blacklist was configured and the mail server is within it: ``{"mailServerBlacklisted": true}``
+
+On success: a object with a ``mailLoginToken`` of the type string
+
+#### example response
+
+```
+{
+  "mailLoginToken": "dhdgfssgsdgd"
+}
+```
+
+#### see
+
+- [mail black and whitelist concept](../concept/mail-blackwhitelist.md)
+
+## POST /auth/sign-in-by-mail-code
+
+Use this to finish authenticating.
+
+### Request
+
+see [this JSON schema](../api/signinbymailcoderequest.md)
+
+#### example request
+
+```
+{
+  "receivedCode": "ein test login",
+  "mailLoginToken": "dhdgfssgsdgd"
+}
+```
+
+### Response
+
+If the request body is malformed: HTTP status code 400 Bad Request
+
+If there were to many wrong attempts: HTTP status code 410 Gone
+
+If the mail login token is unknown: HTTP status code 410 Gone
+
+If the received code is wrong and it can be tried again: HTTP status code 403 Forbidden
+
+On success: A object with a ``mailAuthToken`` of the type string
+
+#### example response
+
+``{"mailAuthToken": "wthdktjdejd"}``