Update Docs

docs/API/README.md

@@ -1,82 +1,128 @@
-=== General ===
+# 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>)
+
+    /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:
+    /api/v1/user/provision/maxmuster
 
-{
-    "auth": {
-        "service": "<servicename>",
-        "token": "<servicetoken>"
+## 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 ===
+## 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>"
+    {
+        "auth": {
+            "service": "<servicename>",
+            "token": "<servicetoken>"
+        },
+        "data": {
+            "<key>": "<value>",
+            "<key>": "<value>"
+        }
     }
-}
 
-=== Browser Authorization Flow: Fully interactive ===
-_Insert explanation here_
+## 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>
+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 ===
+## 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
+
+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 ===
+## 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
+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>`
+4. The User presents their certificate or follows the instructions on-screen to create a new certificate (and confirms the metadata transmission)
+5. The SSO calls a service's script that sets the OTP for the user (as a password or dedicated otp code)
+6. 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 ===
+## 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/
+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
+
+## Grant: Create (E)
+_Generates a new grant and returns information useful for identifying the grant_
+
+**Request:**
+
+    URL:
+    /api/v1/grant/create
+        
+    Body:
+    {
+        ... auth ...
+        "data": {}
+    }
+
+**Response:**
+
+    {
+        "grant": "<Generated  Grant  ID,  Alphanumeric>",
+        "service": "<Requesting  Service's  Name,  Alphanumeric>",
+        "create": "<Unix  Timestamp  at  creation  time,  Numeric>",
+        "result": "created"
+    }