opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-08-01 19:25:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update organisation http api

Browse Source 
make the distinction clearer between /api/org and /api/orgs and that
basic auth must be used for the /api/orgs resource
This commit is contained in:
Marcus Efraimsson
2018-06-29 19:08:38 +02:00
parent aae3b568f3
commit cdaeb1578d
1 changed files with 192 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

370
docs/sources/http_api/org.md
View File

@ -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,135 +43,7 @@ Content-Type: application/json
`GET /api/org/users`
**Example Request**:
```http
GET /api/orgs/1 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**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Get Organisation by Name
`GET /api/orgs/name/:orgName`
**Example Request**:
```http
GET /api/orgs/name/Main%20Org%2E 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/name/Main%20Org%2E
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Create Organisation
`POST /api/orgs`
**Example Request**:
```http
POST /api/orgs HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
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**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Update current Organisation
`PUT /api/org`
**Example Request**:
```http
PUT /api/org HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Get all users within the actual organisation
`GET /api/org/users`
**Example Request**:
```http
GET /api/org/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Add a new user to the actual organisation
`POST /api/org/users`
Adds a global user to the actual organisation.
**Example Request**:
```http
POST /api/org/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
**Example Request**:
```http
GET /api/org/users HTTP/1.1
@ -195,36 +73,7 @@ Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
`DELETE /api/org/users/:userId`
**Example Request**:
```http
DELETE /api/org/users/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
# Organisations
## Search all Organisations
`GET /api/orgs`
**Example Request**:
```http
GET /api/orgs HTTP/1.1
Accept: application/json
**Example Response**:
```http
@ -250,7 +99,7 @@ Content-Type: application/json
```http
HTTP/1.1 200
Content-Type: application/json
Content-Type: application/json
```
@ -272,19 +121,181 @@ Content-Type: application/json
```http
HTTP/1.1 200
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Content-Type: application/json
```
### Add a new user to the current organisation
`POST /api/org/users`
Adds a global user to the current organisation.
**Example Request**:
```http
POST /api/org/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Admin Organisations API
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`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**:
```http
GET /api/orgs/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
### Get Organisation by Name
`GET /api/orgs/name/:orgName`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**:
```http
GET /api/orgs/name/Main%20Org%2E HTTP/1.1
Accept: application/json
Content-Type: application/json
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
### Create Organisation
`POST /api/orgs`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**:
```http
POST /api/orgs HTTP/1.1
Accept: application/json
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 users.allow_org_create to true in ini file
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
### 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
```
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
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
### 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**:
```http
PUT /api/orgs/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
### 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
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
### Get Users in Organisation
`GET /api/orgs/:orgId/users`
@ -303,11 +314,12 @@ Content-Type: application/json
**Example Response**:
Content-Type: application/json
```http
HTTP/1.1 200
Content-Type: application/json
[
```
### Add User in Organisation
`POST /api/orgs/:orgId/users`
@ -315,7 +327,6 @@ Update Organisation, fields *Address 1*, *Address 2*, *City* are not implemented
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**:
Accept: application/json
```http
POST /api/orgs/1/users HTTP/1.1
@ -331,16 +342,17 @@ Content-Type: application/json
Content-Type: application/json
```
## 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
Content-Type: application/json
Accept: application/json
Content-Type: application/json
@ -352,17 +364,18 @@ Content-Type: application/json
HTTP/1.1 200
Content-Type: application/json
```
### 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
Content-Type: application/json
Accept: application/json
Content-Type: application/json
```
@ -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**: