Gatekeeper/docs/API/README.md

# 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>`
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
_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

## 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"
    }

**Errors:**

    {
        "error": {
            "message": "<Exception Message>" (500)
        }
    }

## Grant: Destroy (E)
_Deletes the identified grant from the system and invalidates all Session Tickets potentially issued in name of the Grant_

**Request:**

    URL:
    /api/v1/grant/destroy/<Grant ID>
        
    Body:
    {
        ... auth ...
        "data": {}
    }

**Response:**

    {
        "result": "destroyed"
    }

**Errors:**

    {
        "error": {
            "message": "not found" (404) //
            "message": "<Exception Message>" (500)
        }
    }

## Grant: Status (E)
_Fetch Authorization Status of Grant and get a list of data associated with the grant, such as creation time_

**Request:**

    URL:
    /api/v1/grant/status/<Grant ID>
        
    Body:
    {
        ... auth ...
        "data": {}
    }

**Response:**

    {
        "grant": "<Generated  Grant  ID,  Alphanumeric>",
        "service": "<Requesting  Service's  Name,  Alphanumeric>",
        "create": "<Unix  Timestamp  at  creation  time,  Numeric>",
        "status": "created",//
        "status": "approved",
        -> "ticket": "<Ticket ID>",
        "result": "ok"
    }

**Errors:**

    {
        "error": {
            "message": "not found" (404) //
            "message": "<Exception Message>" (500)
        }
    }