WOCAT » QCAT

h1. API Authentification 

The following is a proposed authentication mechanism for handling mobile app requests. This is to facilitate other API endpoints allowing users to create cases, upload images and edit cases.

h2. User authentification and authorisation

* Use the existing API Token for application authorisation

* Use a second token for the user authentification. This can be solved bei either one of the following options:

** A: Using the existing django-based session ID, same as the web gui.

** B:  Create a Secondary authentication table, as follows:

*** One to many relationship to the Registered UserID (different mobile devices should be possible)

*** 3 fields --> 'UserID', UserToken' & 'time_stamp'  

* When an API request to create a case, upload images or edit cases is received, follow the following use workflow:

#  Authenticate with the API Token to ensure user has access to API

#  Check if the Authenticated User has an 'unexpired' UserToken

## A time limit is used to designate stale/fresh User Tokens

* *Use case 1: User has no UserToken:*

# User has to authenticate to receive a UserToken 

# Response is sent and the UserToken is included. This is the initial handshake

# Time stamp is updated

* *Use case 2:  User has an Unexpired UserToken:*

# Request is accepted

# Time stamp is extended

# Response is served

* *Use case 3: User has an Expired UserToken:*

#  User is re-authenticated with the API Token

# UserToken is refreshed

# Response is sent and the new UserToken is included

#  Time stamp is updated

* *Use case 4: User has Incorrect UserToken:*

#  Invalid Response is sent

h2. Case locking mechanism

*Problem:*

* The web application contains a locking mechanism: A draft version is locked as long as a case open in an editor/form. (* Timeout?*)

* This locking mechanism doesn't work with an offline application, because:

** The server only knows when he sends or receives data, but it can't tell, if sent data is used for editing or view only. 

** Locking as long as the application is offline won't work, as that can take days.

* *Possible solutions:*

* The server receives case data (JSON)  as POST on  respective API endpoint (for a certain configuration/identifier):

# Checking, if the latest version of the case is either _'active'_ or  _'draft'_

# When latest version is _'draft'_, compares the last update timestamp to the timestamp of the UserToken 

* *Use case 1: The latest version is _'active'_: *

# Creates a new draft version with the sent JSON

* *Use case 2: The latest version is not _'draft'_ and not _'active'_:*

# Data upload is rejected with: 'Case under review. Can't be updated'

* *Use case 3: The latest version is _'draft'_:*

# Checks if timestamp of last update on server is newer than the  UserToken timestamp

* *Use case 4: UserToken timestamp is newer than update timestamp on server:*

# Merge sent JSON to draft version.

* *User case 5: Update timestamp on server is newer than UserToken timestamp:*

# Case was updated over another device / or over website

# Data upload is rejected with: 'Newer version exists.'