D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
share
/
grafana
/
docs
/
sources
/
developers
/
http_api
/
Filename :
org.md
back
Copy
--- 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 labels: products: - enterprise - oss 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 { "id":1, "name":"Main Org." } ``` ### 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 [ { "orgId": 1, "userId": 1, "email": "admin@localhost", "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56", "login": "admin", "role": "Admin", "lastSeenAt": "2019-08-09T11:02:49+02:00", "lastSeenAtAge": "< 1m" } ] ``` ### 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 [ { "userId": 1, "login": "admin", "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56" } ] ``` ### 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 { "role": "Viewer", } ``` **Example Response**: ```http HTTP/1.1 200 Content-Type: application/json {"message":"Organization user updated"} ``` ### 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 {"message":"User removed from organization"} ``` ### 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 { "name":"Main Org." } ``` **Example Response**: ```http HTTP/1.1 200 Content-Type: application/json {"message":"Organization updated"} ``` ### 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 { "role": "Admin", "loginOrEmail": "admin" } ``` **Example Response**: ```http HTTP/1.1 200 Content-Type: application/json {"message":"User added to organization","userId":1} ``` ## 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 { "id":1, "name":"Main Org.", "address":{ "address1":"", "address2":"", "city":"", "zipCode":"", "state":"", "country":"" } } ``` ### 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 { "id":1, "name":"Main Org.", "address":{ "address1":"", "address2":"", "city":"", "zipCode":"", "state":"", "country":"" } } ``` ### 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 { "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 value 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 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 [ { "id":1, "name":"Main Org." } ] ``` ### 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 { "name":"Main Org 2." } ``` **Example Response**: ```http HTTP/1.1 200 Content-Type: application/json {"message":"Organization updated"} ``` ### 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 {"message":"Organization deleted"} ``` ### 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 [ { "orgId":1, "userId":1, "email":"admin@mygraf.com", "login":"admin", "role":"Admin" } ] ``` ### 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 { "loginOrEmail":"user", "role":"Viewer" } ``` **Example Response**: ```http HTTP/1.1 200 Content-Type: application/json {"message":"User added to organization", "userId": 1} ``` ### 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 { "role":"Admin" } ``` **Example Response**: ```http HTTP/1.1 200 Content-Type: application/json {"message":"Organization user updated"} ``` ### 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 {"message":"User removed from organization"} ```