mirror of
https://github.com/grafana/grafana.git
synced 2025-02-16 10:24:54 -06:00
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
This commit is contained in:
Marcus Efraimsson
parent
aae3b568f3
commit
cdaeb1578d
@ -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 Organisation by Id
|
||||
|
||||
`GET /api/orgs/:orgId`
|
||||
|
||||
**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
|
||||
|
||||
{
|
||||
"id":1,
|
||||
"name":"Main Org.",
|
||||
"address":{
|
||||
"address1":"",
|
||||
"address2":"",
|
||||
"city":"",
|
||||
"zipCode":"",
|
||||
"state":"",
|
||||
"country":""
|
||||
}
|
||||
}
|
||||
```
|
||||
## 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
|
||||
|
||||
{
|
||||
"id":1,
|
||||
"name":"Main Org.",
|
||||
"address":{
|
||||
"address1":"",
|
||||
"address2":"",
|
||||
"city":"",
|
||||
"zipCode":"",
|
||||
"state":"",
|
||||
"country":""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Create Organisation
|
||||
|
||||
`POST /api/orgs`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
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**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"orgId":"1",
|
||||
"message":"Organization created"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
{
|
||||
"name":"Main Org."
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"Organization updated"}
|
||||
```
|
||||
|
||||
## Get all users within the actual organisation
|
||||
### Get all users within the current organisation
|
||||
|
||||
`GET /api/org/users`
|
||||
|
||||
@ -195,36 +73,7 @@ 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
|
||||
|
||||
{
|
||||
"role": "Admin",
|
||||
"loginOrEmail": "admin"
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"User added to organization"}
|
||||
```
|
||||
|
||||
## Updates the given user
|
||||
### Updates the given user
|
||||
|
||||
`PATCH /api/org/users/:userId`
|
||||
|
||||
@ -250,7 +99,7 @@ Content-Type: application/json
|
||||
{"message":"Organization user updated"}
|
||||
```
|
||||
|
||||
## Delete user in actual organisation
|
||||
### Delete user in current organisation
|
||||
|
||||
`DELETE /api/org/users/:userId`
|
||||
|
||||
@ -272,19 +121,181 @@ Content-Type: application/json
|
||||
{"message":"User removed from organization"}
|
||||
```
|
||||
|
||||
# Organisations
|
||||
### Update current Organisation
|
||||
|
||||
## Search all Organisations
|
||||
`PUT /api/org`
|
||||
|
||||
**Example Request**:
|
||||
|
||||
```http
|
||||
PUT /api/org HTTP/1.1
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||
|
||||
{
|
||||
"name":"Main Org."
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"Organization updated"}
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
{
|
||||
"role": "Admin",
|
||||
"loginOrEmail": "admin"
|
||||
}
|
||||
```
|
||||
|
||||
**Example Response**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{"message":"User added to organization"}
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
{
|
||||
"id":1,
|
||||
"name":"Main Org.",
|
||||
"address":{
|
||||
"address1":"",
|
||||
"address2":"",
|
||||
"city":"",
|
||||
"zipCode":"",
|
||||
"state":"",
|
||||
"country":""
|
||||
}
|
||||
}
|
||||
```
|
||||
### 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
|
||||
|
||||
{
|
||||
"id":1,
|
||||
"name":"Main Org.",
|
||||
"address":{
|
||||
"address1":"",
|
||||
"address2":"",
|
||||
"city":"",
|
||||
"zipCode":"",
|
||||
"state":"",
|
||||
"country":""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
{
|
||||
"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**:
|
||||
|
||||
```http
|
||||
HTTP/1.1 200
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"orgId":"1",
|
||||
"message":"Organization created"
|
||||
}
|
||||
```
|
||||
|
||||
### 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**:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user