apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues 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
pull/12471/head
Marcus Efraimsson 8 years ago
parent aae3b568f3
commit cdaeb1578d
No known key found for this signature in database
GPG Key ID: EBFE0FB04612DD4A
1 changed files with 119 additions and 105 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 224
      docs/sources/http_api/org.md

224
docs/sources/http_api/org.md
Unescape View File

@ -12,7 +12,13 @@ parent = "http_api"
# Organisation 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/` `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**: **Example Request**:
```http ```http
GET /api/orgs/1 HTTP/1.1 GET /api/org/users HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk 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**: **Example Response**:
@ -58,33 +62,33 @@ to the request http url, like http://admin:admin@localhost:3000/api/orgs/1
HTTP/1.1 200 HTTP/1.1 200
Content-Type: application/json Content-Type: application/json
{ [
"id":1, {
"name":"Main Org.", "orgId":1,
"address":{ "userId":1,
"address1":"", "email":"admin@mygraf.com",
"address2":"", "login":"admin",
"city":"", "role":"Admin"
"zipCode":"",
"state":"",
"country":""
} }
} ]
``` ```
## Get Organisation by Name
`GET /api/orgs/name/:orgName` ### Updates the given user
`PATCH /api/org/users/:userId`
**Example Request**: **Example Request**:
```http ```http
GET /api/orgs/name/Main%20Org%2E HTTP/1.1 PATCH /api/org/users/1 HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk 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**: **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 HTTP/1.1 200
Content-Type: application/json Content-Type: application/json
{ {"message":"Organization user updated"}
"id":1,
"name":"Main Org.",
"address":{
"address1":"",
"address2":"",
"city":"",
"zipCode":"",
"state":"",
"country":""
}
}
``` ```
## Create Organisation ### Delete user in current organisation
`POST /api/orgs` `DELETE /api/org/users/:userId`
**Example Request**: **Example Request**:
```http ```http
POST /api/orgs HTTP/1.1 DELETE /api/org/users/1 HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk 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**: **Example Response**:
@ -132,14 +118,10 @@ Note: The api will work in the following two ways
HTTP/1.1 200 HTTP/1.1 200
Content-Type: application/json Content-Type: application/json
{ {"message":"User removed from organization"}
"orgId":"1",
"message":"Organization created"
}
``` ```
### Update current Organisation
## Update current Organisation
`PUT /api/org` `PUT /api/org`
@ -165,17 +147,24 @@ Content-Type: application/json
{"message":"Organization updated"} {"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**: **Example Request**:
```http ```http
GET /api/org/users HTTP/1.1 POST /api/org/users HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"role": "Admin",
"loginOrEmail": "admin"
}
``` ```
**Example Response**: **Example Response**:
@ -184,35 +173,29 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
HTTP/1.1 200 HTTP/1.1 200
Content-Type: application/json Content-Type: application/json
[ {"message":"User added to organization"}
{
"orgId":1,
"userId":1,
"email":"admin@mygraf.com",
"login":"admin",
"role":"Admin"
}
]
``` ```
## 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**: **Example Request**:
```http ```http
POST /api/org/users HTTP/1.1 GET /api/orgs/1 HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"role": "Admin",
"loginOrEmail": "admin"
}
``` ```
**Example Response**: **Example Response**:
@ -221,24 +204,31 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
HTTP/1.1 200 HTTP/1.1 200
Content-Type: application/json 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**: **Example Request**:
```http ```http
PATCH /api/org/users/1 HTTP/1.1 GET /api/orgs/name/Main%20Org%2E HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"role": "Viewer",
}
``` ```
**Example Response**: **Example Response**:
@ -247,21 +237,40 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
HTTP/1.1 200 HTTP/1.1 200
Content-Type: application/json 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**: **Example Request**:
```http ```http
DELETE /api/org/users/1 HTTP/1.1 POST /api/orgs HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: 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**: **Example Response**:
@ -269,22 +278,24 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
HTTP/1.1 200 HTTP/1.1 200
Content-Type: application/json Content-Type: application/json
{"message":"User removed from organization"} {
"orgId":"1",
"message":"Organization created"
}
``` ```
# Organisations ### Search all Organisations
## Search all Organisations
`GET /api/orgs` `GET /api/orgs`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**: **Example Request**:
```http ```http
GET /api/orgs HTTP/1.1 GET /api/orgs HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
``` ```
Note: The api will only work when you pass the admin name and password 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 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` `PUT /api/orgs/:orgId`
Update Organisation, fields *Address 1*, *Address 2*, *City* are not implemented yet. 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**: **Example Request**:
@ -315,7 +327,6 @@ Update Organisation, fields *Address 1*, *Address 2*, *City* are not implemented
PUT /api/orgs/1 HTTP/1.1 PUT /api/orgs/1 HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{ {
"name":"Main Org 2." "name":"Main Org 2."
@ -331,16 +342,17 @@ Content-Type: application/json
{"message":"Organization updated"} {"message":"Organization updated"}
``` ```
## Delete Organisation ### Delete Organisation
`DELETE /api/orgs/:orgId` `DELETE /api/orgs/:orgId`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**: **Example Request**:
```http ```http
DELETE /api/orgs/1 HTTP/1.1 DELETE /api/orgs/1 HTTP/1.1
Accept: application/json Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
``` ```
**Example Response**: **Example Response**:
@ -352,17 +364,18 @@ Content-Type: application/json
{"message":"Organization deleted"} {"message":"Organization deleted"}
``` ```
## Get Users in Organisation ### Get Users in Organisation
`GET /api/orgs/:orgId/users` `GET /api/orgs/:orgId/users`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**: **Example Request**:
```http ```http
GET /api/orgs/1/users HTTP/1.1 GET /api/orgs/1/users HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
``` ```
Note: The api will only work when you pass the admin name and password 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 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` `POST /api/orgs/:orgId/users`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**: **Example Request**:
```http ```http
POST /api/orgs/1/users HTTP/1.1 POST /api/orgs/1/users HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{ {
"loginOrEmail":"user", "loginOrEmail":"user",
"role":"Viewer" "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**: **Example Response**:
@ -413,17 +425,18 @@ Content-Type: application/json
{"message":"User added to organization"} {"message":"User added to organization"}
``` ```
## Update Users in Organisation ### Update Users in Organisation
`PATCH /api/orgs/:orgId/users/:userId` `PATCH /api/orgs/:orgId/users/:userId`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**: **Example Request**:
```http ```http
PATCH /api/orgs/1/users/2 HTTP/1.1 PATCH /api/orgs/1/users/2 HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{ {
"role":"Admin" "role":"Admin"
@ -439,17 +452,18 @@ Content-Type: application/json
{"message":"Organization user updated"} {"message":"Organization user updated"}
``` ```
## Delete User in Organisation ### Delete User in Organisation
`DELETE /api/orgs/:orgId/users/:userId` `DELETE /api/orgs/:orgId/users/:userId`
Only works with Basic Authentication (username and password), see [introduction](#admin-organisations-api).
**Example Request**: **Example Request**:
```http ```http
DELETE /api/orgs/1/users/2 HTTP/1.1 DELETE /api/orgs/1/users/2 HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
``` ```
**Example Response**: **Example Response**:

Write Preview
Loading…
Cancel
Save