mirror of
https://github.com/grafana/grafana.git
synced 2025-07-29 15:02:28 +08:00
c1c48dd610
* Use relative aliases for all non-current Grafana aliases
Prevents non-latest documentation "stealing" the page away from latest
and through permanent redirects for latest pages that no longer exist.
The redirected pages are indexed by search engines but our robots.txt
forbids them crawling the non-latest page.
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Remove aliases from shared pages
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Rewrite all current latest aliases to be next
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Fix typo in latest alias
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Remove all current page aliases
find docs/sources -type f -name '*.md' -exec sed -z -i 's#\n *- /docs/grafana/next/[^\n]*\n#\n#' {} \;
find docs/sources -type f -name '*.md' -exec sed -Ez -i 's#\n((aliases:\n *-)|aliases:\n)#\n\2#' {} \;
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Prettier
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
662 lines
13 KiB
Markdown
662 lines
13 KiB
Markdown
---
|
|
aliases:
|
|
- ../../http_api/org/
|
|
- ../../http_api/organization/
|
|
description: Grafana Organization HTTP API
|
|
keywords:
|
|
- grafana
|
|
- http
|
|
- documentation
|
|
- api
|
|
- organization
|
|
title: Organization HTTP API
|
|
---
|
|
|
|
# Organization API
|
|
|
|
The Organization HTTP API is divided in two resources, `/api/org` (current organization)
|
|
and `/api/orgs` (admin organizations). One big difference between these are that
|
|
the admin of all organizations API only works with basic authentication, see [Admin Organizations API](#admin-organizations-api) for more information.
|
|
|
|
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../administration/roles-and-permissions/access-control/custom-role-actions-scopes/" >}}) for more information.
|
|
|
|
## Current Organization API
|
|
|
|
### Get current Organization
|
|
|
|
`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
|
|
GET /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 current organization
|
|
|
|
`GET /api/org/users`
|
|
|
|
Returns all org users within the current organization.
|
|
Accessible to users with org admin role.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| -------------- | -------- |
|
|
| org.users:read | 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
|
|
|
|
```
|
|
|
|
### Get all users within the current organization (lookup)
|
|
|
|
`GET /api/org/users/lookup`
|
|
|
|
Returns all org users within the current organization, but with less detailed information.
|
|
Accessible to users with org admin role, admin in any folder or admin of any team.
|
|
Mainly used by Grafana UI for providing list of users when adding team members and
|
|
when editing folder/dashboard permissions.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| -------------- | -------- |
|
|
| org.users:read | users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/org/users/lookup HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
### Updates the given user
|
|
|
|
`PATCH /api/org/users/:userId`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| --------------- | -------- |
|
|
| org.users:write | users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PATCH /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
|
|
|
|
```
|
|
|
|
### Delete user in current organization
|
|
|
|
`DELETE /api/org/users/:userId`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------------- | -------- |
|
|
| org.users:remove | users:\* |
|
|
|
|
**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
|
|
|
|
```
|
|
|
|
### Update current Organization
|
|
|
|
`PUT /api/org`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------- | ----- |
|
|
| orgs:write | N/A |
|
|
|
|
**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
|
|
|
|
```
|
|
|
|
### 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:\* |
|
|
|
|
**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 Organizations API
|
|
|
|
The Admin Organizations 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 Organization by Id
|
|
|
|
`GET /api/orgs/:orgId`
|
|
|
|
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:read | N/A |
|
|
|
|
**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 Organization by Name
|
|
|
|
`GET /api/orgs/name/:orgName`
|
|
|
|
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 | 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**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
### Create Organization
|
|
|
|
`POST /api/orgs`
|
|
|
|
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 | Note |
|
|
| ----------- | ----- | ------------------------------ |
|
|
| orgs:create | N/A | Needs to be assigned globally. |
|
|
|
|
**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 value users.allow_org_create to true in ini file
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
### Search all Organizations
|
|
|
|
`GET /api/orgs?perpage=10&page=1`
|
|
|
|
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 | Note |
|
|
| --------- | ----- | ------------------------------ |
|
|
| orgs:read | N/A | Needs to be assigned globally. |
|
|
|
|
**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
|
|
|
|
Default value for the `perpage` parameter is `1000` and for the `page` parameter is `0`.
|
|
|
|
**Example Response**:
|
|
|
|
```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).
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------- | ----- |
|
|
| orgs:write | N/A |
|
|
|
|
**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 Organization
|
|
|
|
`DELETE /api/orgs/:orgId`
|
|
|
|
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
|
|
Accept: application/json
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
### Get Users in Organization
|
|
|
|
`GET /api/orgs/:orgId/users`
|
|
|
|
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 |
|
|
| -------------- | -------- |
|
|
| org.users:read | users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
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
|
|
[
|
|
```
|
|
|
|
### Add User in Organization
|
|
|
|
`POST /api/orgs/:orgId/users`
|
|
|
|
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 |
|
|
| ------------- | -------- |
|
|
| org.users:add | users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/orgs/1/users HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
### Update Users in Organization
|
|
|
|
`PATCH /api/orgs/:orgId/users/:userId`
|
|
|
|
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 |
|
|
| --------------- | -------- |
|
|
| org.users:write | users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PATCH /api/orgs/1/users/2 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
### Delete User in Organization
|
|
|
|
`DELETE /api/orgs/:orgId/users/:userId`
|
|
|
|
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 |
|
|
| ---------------- | -------- |
|
|
| org.users:remove | users:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/orgs/1/users/2 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|