Added application and project roles validation for API procedure calls

4 files changed, 65 insertions, 39 deletions

diff --git a/doc/api-authentication.markdown b/doc/api-authentication.markdown
index 962e5b1b..3ba1e8f5 100644
--- a/doc/api-authentication.markdown
+++ b/doc/api-authentication.markdown
@@ -1,48 +1,26 @@
 API Authentication
 ==================
 
-Default method (HTTP Basic)
----------------------------
+API endpoint
+------------
+
+URL: `https://YOUR_SERVER/jsonrpc.php`
 
-The API credentials are available on the settings page.
 
-- API end-point: `https://YOUR_SERVER/jsonrpc.php`
+Default method (HTTP Basic)
+---------------------------
 
-If you want to use the "application api":
+### Application credentials
 
 - Username: `jsonrpc`
 - Password: API token on the settings page
 
-Otherwise for the "user api", just use the real username/passsword.
+### User credentials
+
+- Use the real username and password
 
 The API use the [HTTP Basic Authentication Scheme described in the RFC2617](http://www.ietf.org/rfc/rfc2617.txt).
-If there is an authentication error, you will receive the HTTP status code `401 Not Authorized`.
-
-### Authorized User API procedures
-
-- getMe
-- getMyDashboard
-- getMyActivityStream
-- createMyPrivateProject
-- getMyProjectsList
-- getMyProjects
-- getTimezone
-- getVersion
-- getDefaultTaskColor
-- getDefaultTaskColors
-- getColorList
-- getProjectById
-- getTask
-- getTaskByReference
-- getAllTasks
-- openTask
-- closeTask
-- moveTaskPosition
-- createTask
-- updateTask
-- getBoard
-- getProjectActivity
-- getMyOverdueTasks
+
 
 Custom HTTP header
 ------------------
@@ -64,3 +42,14 @@ curl \
 -d '{"jsonrpc": "2.0", "method": "getAllProjects", "id": 1}' \
 http://localhost/kanboard/jsonrpc.php
 ```
+
+Authentication error
+--------------------
+
+If the credentials are wrong, you will receive a `401 Not Authorized` and the corresponding JSON response.
+
+
+Authorization error
+-------------------
+
+If the connected user is not allowed to access to the resource, you will receive a `403 Forbidden`.
diff --git a/doc/api-json-rpc.markdown b/doc/api-json-rpc.markdown
index bb14b008..0f922a7c 100644
--- a/doc/api-json-rpc.markdown
+++ b/doc/api-json-rpc.markdown
@@ -8,25 +8,25 @@ There are two types of API access:
 
 ### Application API
 
-- Access to the API with the user "jsonrpc" and the token available in settings
+- Access to the API with the user "jsonrpc" and the token available on the settings page
 - Access to all procedures
 - No permission checked
 - There is no user session on the server
+- No access to procedures that starts with "My..." (example: "getMe" or "getMyProjects")
 - Example of possible clients: tools to migrate/import data, create tasks from another system, etc...
 
 ### User API
 
 - Access to the API with the user credentials (username and password)
-- Access to a restricted set of procedures
-- The project permissions are checked
+- Application role and project permissions are checked for each procedure
 - A user session is created on the server
-- Example of possible clients: mobile/desktop application, command line utility, etc...
+- Example of possible clients: native mobile/desktop application, command line utility, etc...
 
 Security
 --------
 
-- Always use HTTPS with a valid certificate
-- If you make a mobile application, it's your job to store securely the user credentials on the device
+- Always use HTTPS with a valid certificate (avoid clear text communication)
+- If you make a mobile application, it's your responsability to store securely the user credentials on the device
 - After 3 authentication failure on the user api, the end-user have to unlock his account by using the login form
 - Two factor authentication is not yet available through the API
 
diff --git a/doc/api-project-permission-procedures.markdown b/doc/api-project-permission-procedures.markdown
index 2844ae3c..d5e9b066 100644
--- a/doc/api-project-permission-procedures.markdown
+++ b/doc/api-project-permission-procedures.markdown
@@ -272,3 +272,36 @@ Response example:
     "result": true
 }
 ```
+
+## getProjectUserRole
+
+- Purpose: **Get the role of a user for a given project**
+- Parameters:
+    - **project_id** (integer, required)
+    - **user_id** (integer, required)
+- Result on success: **role name**
+- Result on failure: **false**
+
+Request example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "getProjectUserRole",
+    "id": 2114673298,
+    "params": [
+        "2",
+        "3"
+    ]
+}
+```
+
+Response example:
+
+```json
+{
+    "jsonrpc": "2.0",
+    "id": 2114673298,
+    "result": "project-viewer"
+}
+```
diff --git a/doc/api-project-procedures.markdown b/doc/api-project-procedures.markdown
index f8e2cc5e..3f8d33c2 100644
--- a/doc/api-project-procedures.markdown
+++ b/doc/api-project-procedures.markdown
@@ -7,6 +7,8 @@ API Project Procedures
 - Parameters:
     - **name** (string, required)
     - **description** (string, optional)
+    - **owner_id** (integer, optional)
+    - **identifier** (string, optional)
 - Result on success: **project_id**
 - Result on failure: **false**
 
@@ -186,6 +188,8 @@ Response example:
     - **project_id** (integer, required)
     - **name** (string, required)
     - **description** (string, optional)
+    - **owner_id** (integer, optional)
+    - **identifier** (string, optional)
 - Result on success: **true**
 - Result on failure: **false**