Work on API Documentation

docs/API/README.md

@@ -0,0 +1,82 @@
+=== General ===
+The API is using versioning to provide compatibility with legacy services.
+The base URL looks like this:
+/api/<version>/<interface>/<action>(/<id or attibute>)
+
+So, for example,
+/api/v1/user/provision/maxmuster
+
+=== Request body: Service authentication ===
+In order to use APIs that are limited to access by their corresponding service,
+add the following parameters in request body:
+
+{
+    "auth": {
+        "service": "<servicename>",
+        "token": "<servicetoken>"
+    }
+}
+
+=== Request body: Request data ===
+In order to provide additional parameters with a request, add them to the data node.
+The request body might have a similar structure to this :
+
+{
+    "auth": {
+        "service": "<servicename>",
+        "token": "<servicetoken>"
+    },
+    "data": {
+        "<key>": "<value>",
+        "<key>": "<value>"
+    }
+}
+
+=== Browser Authorization Flow: Fully interactive ===
+_Insert explanation here_
+1. The user might want to log into a service by executing an action (might be a button or other actuator) like "Log in using domain.tld SSO".
+2. The corresponding service then fetches the Gatekeeper Instance's API in order to generate a _GRANT_ (See: Grant Create)
+3. On success, Gatekeeper API returns the Grant ID for the service to save in memory, with result status "created"
+4. The Service now has the obligation to redirect the user to domain.tld/sso/<grant id>
+5. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission)
+6. A session ticket is generated (internally) and the user is being redirected back to the service's callback url
+7. The service fetches the session ticket id by requesting grant status (See: Grant Status) or using ticket fetch with the grant id (See: Ticket Fetch)
+8. The service fetches the session ticket data by requesting ticket status (See: Ticket Status) using the ticket id
+-> The user is logged into the service now
+
+=== Browser Authorization Flow: Partially interactive ===
+_Insert explanation here_
+Pre. The user indicates some kind of wish to authenticate
+1. The corresponding service fetches the Gatekeeper Instance's API in order to generate a _GRANT_ (See: Grant Create)
+2. On success, Gatekeeper API returns the Grant ID for the service to save in memory, with result status "created"
+_User Perspective_
+3.1 The user might want to log into the service by clicking on a link, an action (might be a button or other actuator) targeting domain.tld/sso/<grant id>
+3.2 The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission)
+3.3 A session ticket is generated (internally) and the browser window closes
+_Service Perspective_
+6. The service regularly checks for a session ticket id by requesting grant status (See: Grant Status) or using ticket fetch with the grant id (See: Ticket Fetch)
+7. On success the service fetches the session ticket data by requesting ticket status (See: Ticket Status) using the ticket id
+-> The user is logged into the service now
+
+=== Browser Authorization Flow: OTP ===
+_Insert explanation here_
+1. The user might want to log into a service by executing an action (might be a button or other actuator) like "Log in using domain.tld SSO".
+2. The corresponding service then fetches the Gatekeeper Instance's API in order to generate a _GRANT_ (See: Grant Create)
+3. On success, Gatekeeper API returns the Grant ID for the service to add to a link, suggesting the user to visit: domain.tld/sso/<grant id>
+5. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission)
+6. The SSO calls a service's script that sets the OTP for the user (as a password or dedicated otp code)
+7. On Success, a session ticket and an OTP Code is generated and the user is being presented with an openwith: Intent Link containing the user and otp code or instructions to enter the OTP Code in the OTP or Password field of the service ui
+-> The user is logged into the service now
+
+=== Browser Authorization Flow: Reverse OTP ===
+_Insert explanation here_
+1. The user might want to log into a service by executing an action (might be a button or other actuator) like "Log in using domain.tld SSO".
+2. The corresponding service then fetches the Gatekeeper Instance's API in order to generate a _GRANT_ (See: Grant Create)
+3. On success, Gatekeeper API returns the Grant ID and an OTP Code for the service to save in memory, with result status "created"
+4. The Service instructs the user to manually visit domain.tld/otp/
+5. The User types in the OTP Code displayed by the service
+6. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission)
+7. A session ticket is generated and the browser window closes
+8. The service fetches the session ticket id by requesting grant status (See: Grant Status) or using ticket fetch with the grant id (See: Ticket Fetch)
+9. The service fetches the session ticket data by requesting ticket status (See: Ticket Status) using the ticket id
+-> The user is logged into the service now

src/Tor/Controller/TicketApi.php

@@ -82,7 +82,7 @@ class TicketApi extends BaseApi {
 
             $result = [
                 'start' => $ticket->start,
-                'end' = $ticket->end,
+                'end' => $ticket->end,
                 'result' => 'expired'
             ];