AccessControl: Document orgs roles and orgs endpoints (#42171)

* AccessControl: Document `orgs` roles and `orgs` endpoints

* Use maintainer instead of manager

docs/sources/http_api/org.md

@@ -20,6 +20,14 @@ the admin of all organizations API only works with basic authentication, see [Ad
 
 `GET /api/org/`
 
+#### Required permissions
+
+See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
+
+| Action    | Scope |
+| --------- | ----- |
+| orgs:read | N/A   |
+
 **Example Request**:
 
 ```http
@@ -94,6 +102,14 @@ Accessible to users with org admin role, admin in any folder or admin of any tea
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
 ```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
 
 ### Updates the given user
 
@@ -186,6 +202,14 @@ Content-Type: application/json
 
 ### Add a new user to the current organization
 
+`POST /api/org/users`
+
+Adds a global user to the current organization.
+
+#### Required permissions
+
+See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
+
 | Action        | Scope    |
 | ------------- | -------- |
 | org.users:add | users:\* |
@@ -259,6 +283,14 @@ is called `admin` and has permission to use this API).
 | Action    | Scope | Note                           |
 | --------- | ----- | ------------------------------ |
 | orgs:read | N/A   | Needs to be assigned globally. |
+
+**Example Request**:
+
+```http
+GET /api/orgs/name/Main%20Org%2E HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+```
 
 **Example Response**:
 
@@ -293,6 +325,14 @@ Content-Type: application/json
 
 Note: The api will work in the following two ways
 
+1. Need to set GF_USERS_ALLOW_ORG_CREATE=true
+2. Set the config value users.allow_org_create to true in ini file
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
 
 ```
 
@@ -327,6 +367,14 @@ Content-Type: application/json
 
 ```http
 HTTP/1.1 200
+Content-Type: application/json
+
+```
+
+### Update Organization
+
+`PUT /api/orgs/:orgId`
+
 Update Organization, fields _Address 1_, _Address 2_, _City_ are not implemented yet.
 Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
 
@@ -362,6 +410,14 @@ Content-Type: application/json
 Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
 
 #### Required permissions
+
+See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
+
+| Action      | Scope |
+| ----------- | ----- |
+| orgs:delete | N/A   |
+
+**Example Request**:
 
 ```http
 DELETE /api/orgs/1 HTTP/1.1
@@ -396,6 +452,14 @@ Content-Type: application/json
 GET /api/orgs/1/users HTTP/1.1
 Accept: application/json
 Content-Type: application/json
+```
+
+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**:
+
+```http
 HTTP/1.1 200
 Content-Type: application/json
 [
@@ -423,6 +487,14 @@ Content-Type: application/json
 Content-Type: application/json
 
 ```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
 
 ### Update Users in Organization