Project: Grafana (Observability and Analysis / Observability)
File: org.md

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 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 for more information. If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to for more information. `GET /api/org/` Required permissions See note in the 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 /api/org/users` Returns all org users within the current organization. Accessible to users with org admin role. Required permissions See note in the 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 /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 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" } ] ``` `PATCH /api/org/users/:userId` Required permissions See note in the 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 /api/org/users/:userId` Required permissions See note in the 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"} ``` `PUT /api/org` Required permissions See note in the for an

| 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"} ``` `POST /api/org/users` Adds a global user to the current organization. Required permissions See note in the 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} ``` 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 /api/orgs/:orgId` Only works with Basic Authentication (username and password), see . Required permissions See note in the 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 /api/orgs/name/:orgName` Only works with Basic Authentication (username and password), see . Required permissions See note in the 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":"" } } ``` `POST /api/orgs` Only works with Basic Authentication (username and password), see . Required permissions See note in the 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 Need to set GFUSERSALLOWORGCREATE=true Set the config value users.alloworgcreate to true in ini file Example Response: ```http HTTP/1.1 200 Content-Type: application/json { "orgId":"1", "message":"Organization created" } ``` `GET /api/orgs?perpage=10&page=1` Only works with Basic Authentication (username and password), see . Required permissions See note in the for an explanation. | Action | Scope | Note | | | -- | | | orgs:read | N/A | Needs to be assigned

| 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." } ] ``` `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 . Required permissions See note in the 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 /api/orgs/:orgId` Only works with Basic Authentication (username and password), see . Required permissions See note in the 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 /api/orgs/:orgId/users` Only works with Basic Authentication (username and password), see . Required permissions See note in the 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" } ] ``` `POST /api/orgs/:orgId/users` Only works with Basic Authentication (username and password), see . Required permissions See note in the 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} ``` `PATCH /api/orgs/:orgId/users/:userId` Only works with Basic Authentication (username and password), see . Required permissions See note in the 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 /api/orgs/:orgId/users/:userId` Only works with Basic Authentication (username and password), see . Required permissions See note in the 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"} ```