docs: update organisation http api

make the distinction clearer between /api/org and /api/orgs and that
basic auth must be used for the /api/orgs resource

docs/sources/http_api/org.md

@@ -12,7 +12,13 @@ parent = "http_api"
 
 # Organisation API
 
-## Get current Organisation
+The Organisation HTTP API is divided in two resources, `/api/org` (current organisation)
+and `/api/orgs` (admin organisations). One big difference between these are that
+the admin of all organisations API only works with basic authentication, see [Admin Organisations API](#admin-organisations-api) for more information.
+
+## Current Organisation API
+
+### Get current Organisation
 
 `GET /api/org/`
 
@@ -37,20 +43,18 @@ Content-Type: application/json
 }
 ```
 
-## Get Organisation by Id
+### Get all users within the current organisation
 
-`GET /api/orgs/:orgId`
+`GET /api/org/users`
 
 **Example Request**:
 
 ```http
-GET /api/orgs/1 HTTP/1.1
+GET /api/org/users HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 ```
-Note: The api will only work when you pass the admin name and password
-to the request http url, like http://admin:admin@localhost:3000/api/orgs/1
 
 **Example Response**:
 
@@ -58,33 +62,33 @@ to the request http url, like http://admin:admin@localhost:3000/api/orgs/1
 HTTP/1.1 200
 Content-Type: application/json
 
-{
-  "id":1,
-  "name":"Main Org.",
-  "address":{
-    "address1":"",
-    "address2":"",
-    "city":"",
-    "zipCode":"",
-    "state":"",
-    "country":""
+[
+  {
+    "orgId":1,
+    "userId":1,
+    "email":"admin@mygraf.com",
+    "login":"admin",
+    "role":"Admin"
   }
-}
+]
 ```
-## Get Organisation by Name
 
-`GET /api/orgs/name/:orgName`
+### Updates the given user
+
+`PATCH /api/org/users/:userId`
 
 **Example Request**:
 
 ```http
-GET /api/orgs/name/Main%20Org%2E HTTP/1.1
+PATCH /api/org/users/1 HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+{
+  "role": "Viewer",
+}
 ```
-Note: The api will only work when you pass the admin name and password
-to the request http url, like http://admin:admin@localhost:3000/api/orgs/name/Main%20Org%2E
 
 **Example Response**:
 
@@ -92,39 +96,21 @@ to the request http url, like http://admin:admin@localhost:3000/api/orgs/name/Ma
 HTTP/1.1 200
 Content-Type: application/json
 
-{
-  "id":1,
-  "name":"Main Org.",
-  "address":{
-    "address1":"",
-    "address2":"",
-    "city":"",
-    "zipCode":"",
-    "state":"",
-    "country":""
-  }
-}
+{"message":"Organization user updated"}
 ```
 
-## Create Organisation
+### Delete user in current organisation
 
-`POST /api/orgs`
+`DELETE /api/org/users/:userId`
 
 **Example Request**:
 
 ```http
-POST /api/orgs HTTP/1.1
+DELETE /api/org/users/1 HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
-
-{
-  "name":"New Org."
-}
 ```
-Note: The api will work in the following two ways
-1) Need to set GF_USERS_ALLOW_ORG_CREATE=true
-2) Set the config users.allow_org_create to true in ini file
 
 **Example Response**:
 
@@ -132,14 +118,10 @@ Note: The api will work in the following two ways
 HTTP/1.1 200
 Content-Type: application/json
 
-{
-  "orgId":"1",
-  "message":"Organization created"
-}
+{"message":"User removed from organization"}
 ```
 
-
-## Update current Organisation
+### Update current Organisation
 
 `PUT /api/org`
 
@@ -165,17 +147,24 @@ Content-Type: application/json
 {"message":"Organization updated"}
 ```
 
-## Get all users within the actual organisation
+### Add a new user to the current organisation
 
-`GET /api/org/users`
+`POST /api/org/users`
+
+Adds a global user to the current organisation.
 
 **Example Request**:
 
 ```http
-GET /api/org/users HTTP/1.1
+POST /api/org/users HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+{
+  "role": "Admin",
+  "loginOrEmail": "admin"
+}
 ```
 
 **Example Response**:
@@ -184,35 +173,29 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 
-[
-  {
-    "orgId":1,
-    "userId":1,
-    "email":"admin@mygraf.com",
-    "login":"admin",
-    "role":"Admin"
-  }
-]
+{"message":"User added to organization"}
 ```
 
-## Add a new user to the actual organisation
+## Admin Organisations API
 
-`POST /api/org/users`
+The Admin Organisations HTTP API does not currently work with an API Token. API Tokens are currently
+only linked to an organization and an organization role. They cannot be given the permission of server
+admin, only users can be given that permission. So in order to use these API calls you will have to
+use Basic Auth and the Grafana user must have the Grafana Admin permission (The default admin user
+is called `admin` and has permission to use this API).
+
+### Get Organisation by Id
+
+`GET /api/orgs/:orgId`
 
-Adds a global user to the actual organisation.
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
 
 **Example Request**:
 
 ```http
-POST /api/org/users HTTP/1.1
+GET /api/orgs/1 HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
-
-{
-  "role": "Admin",
-  "loginOrEmail": "admin"
-}
 ```
 
 **Example Response**:
@@ -221,24 +204,31 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 
-{"message":"User added to organization"}
+{
+  "id":1,
+  "name":"Main Org.",
+  "address":{
+    "address1":"",
+    "address2":"",
+    "city":"",
+    "zipCode":"",
+    "state":"",
+    "country":""
+  }
+}
 ```
+### Get Organisation by Name
 
-## Updates the given user
+`GET /api/orgs/name/:orgName`
 
-`PATCH /api/org/users/:userId`
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
 
 **Example Request**:
 
 ```http
-PATCH /api/org/users/1 HTTP/1.1
+GET /api/orgs/name/Main%20Org%2E HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
-
-{
-  "role": "Viewer",
-}
 ```
 
 **Example Response**:
@@ -247,21 +237,40 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 
-{"message":"Organization user updated"}
+{
+  "id":1,
+  "name":"Main Org.",
+  "address":{
+    "address1":"",
+    "address2":"",
+    "city":"",
+    "zipCode":"",
+    "state":"",
+    "country":""
+  }
+}
 ```
 
-## Delete user in actual organisation
+### Create Organisation
 
-`DELETE /api/org/users/:userId`
+`POST /api/orgs`
+
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
 
 **Example Request**:
 
 ```http
-DELETE /api/org/users/1 HTTP/1.1
+POST /api/orgs HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+
+{
+  "name":"New Org."
+}
 ```
+Note: The api will work in the following two ways
+1) Need to set GF_USERS_ALLOW_ORG_CREATE=true
+2) Set the config users.allow_org_create to true in ini file
 
 **Example Response**:
 
@@ -269,22 +278,24 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 HTTP/1.1 200
 Content-Type: application/json
 
-{"message":"User removed from organization"}
+{
+  "orgId":"1",
+  "message":"Organization created"
+}
 ```
 
-# Organisations
-
-## Search all Organisations
+### Search all Organisations
 
 `GET /api/orgs`
 
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
+
 **Example Request**:
 
 ```http
 GET /api/orgs HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 ```
 Note: The api will only work when you pass the admin name and password
 to the request http url, like http://admin:admin@localhost:3000/api/orgs
@@ -303,11 +314,12 @@ Content-Type: application/json
 ]
 ```
 
-## Update Organisation
+### Update Organisation
 
 `PUT /api/orgs/:orgId`
 
 Update Organisation, fields *Address 1*, *Address 2*, *City* are not implemented yet.
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
 
 **Example Request**:
 
@@ -315,7 +327,6 @@ Update Organisation, fields *Address 1*, *Address 2*, *City* are not implemented
 PUT /api/orgs/1 HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 
 {
   "name":"Main Org 2."
@@ -331,16 +342,17 @@ Content-Type: application/json
 {"message":"Organization updated"}
 ```
 
-## Delete Organisation
+### Delete Organisation
 
 `DELETE /api/orgs/:orgId`
 
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
+
 **Example Request**:
 
 ```http
 DELETE /api/orgs/1 HTTP/1.1
 Accept: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 ```
 
 **Example Response**:
@@ -352,17 +364,18 @@ Content-Type: application/json
 {"message":"Organization deleted"}
 ```
 
-## Get Users in Organisation
+### Get Users in Organisation
 
 `GET /api/orgs/:orgId/users`
 
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
+
 **Example Request**:
 
 ```http
 GET /api/orgs/1/users HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 ```
 Note: The api will only work when you pass the admin name and password
 to the request http url, like http://admin:admin@localhost:3000/api/orgs/1/users
@@ -384,25 +397,24 @@ Content-Type: application/json
 ]
 ```
 
-## Add User in Organisation
+### Add User in Organisation
 
 `POST /api/orgs/:orgId/users`
 
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
+
 **Example Request**:
 
 ```http
 POST /api/orgs/1/users HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 
 {
   "loginOrEmail":"user",
   "role":"Viewer"
 }
 ```
-Note: The api will only work when you pass the admin name and password
-to the request http url, like http://admin:admin@localhost:3000/api/orgs/1/users
 
 **Example Response**:
 
@@ -413,17 +425,18 @@ Content-Type: application/json
 {"message":"User added to organization"}
 ```
 
-## Update Users in Organisation
+### Update Users in Organisation
 
 `PATCH /api/orgs/:orgId/users/:userId`
 
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
+
 **Example Request**:
 
 ```http
 PATCH /api/orgs/1/users/2 HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 
 {
   "role":"Admin"
@@ -439,17 +452,18 @@ Content-Type: application/json
 {"message":"Organization user updated"}
 ```
 
-## Delete User in Organisation
+### Delete User in Organisation
 
 `DELETE /api/orgs/:orgId/users/:userId`
 
+Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
+
 **Example Request**:
 
 ```http
 DELETE /api/orgs/1/users/2 HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 ```
 
 **Example Response**: