mirror of
https://github.com/grafana/grafana.git
synced 2025-07-28 19:02:29 +08:00
ebb54aea8d
* Fix reference to Grafana CLI - Make relref for relative permalink - Use relative path for unambiguous resolution Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix alerting relref anchor format Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Avoid ambiguous relref lookups by forcing relative resolution Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Remove reference to non-existent shared page Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix links broken in Grafana Cloud using absolute relrefs By resolving the relref absolutely, it refers to the same location regardless of mounted directory. Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Remove trailing slash for bundle independent resolution Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix typo Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * For now, avoid Hugo checking cross repository /docs/grafana-cloud link The path is unlikely to change in the short term and this makes CI completely green for now. Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * No need to specify path for in page anchors Signed-off-by: Jack Baldry <jack.baldry@grafana.com> * Fix prose Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com> --------- Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>
663 lines
13 KiB
Markdown
663 lines
13 KiB
Markdown
---
|
|
aliases:
|
|
- ../../http_api/org/
|
|
- ../../http_api/organization/
|
|
canonical: /docs/grafana/latest/developers/http_api/org/
|
|
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 "/docs/grafana/latest/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
|
|
|
|
```
|