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 for more information.

Current Organization API

Get current Organization

GET /api/org/

Example Request:

  1. GET /api/org/ HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "id":1,
  5. "name":"Main Org."
  6. }

Get all users within the current organization

GET /api/org/users

Example Request:

  1. GET /api/org/users HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. [
  4. {
  5. "orgId":1,
  6. "userId":1,
  7. "email":"admin@mygraf.com",
  8. "login":"admin",
  9. "role":"Admin"
  10. }
  11. ]

Updates the given user

PATCH /api/org/users/:userId

Example Request:

  1. PATCH /api/org/users/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6. "role": "Viewer",
  7. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"Organization user updated"}

Delete user in current organization

DELETE /api/org/users/:userId

Example Request:

  1. DELETE /api/org/users/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"User removed from organization"}

Update current Organization

PUT /api/org

Example Request:

  1. PUT /api/org HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6. "name":"Main Org."
  7. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"Organization updated"}

Add a new user to the current organization

POST /api/org/users

Adds a global user to the current organization.

Example Request:

  1. POST /api/org/users HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6. "role": "Admin",
  7. "loginOrEmail": "admin"
  8. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"User added to organization"}

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.

Example Request:

  1. GET /api/orgs/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "id":1,
  5. "name":"Main Org.",
  6. "address":{
  7. "address1":"",
  8. "address2":"",
  9. "city":"",
  10. "zipCode":"",
  11. "state":"",
  12. "country":""
  13. }
  14. }

Get Organization by Name

GET /api/orgs/name/:orgName

Only works with Basic Authentication (username and password), see introduction.

Example Request:

  1. GET /api/orgs/name/Main%20Org%2E HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "id":1,
  5. "name":"Main Org.",
  6. "address":{
  7. "address1":"",
  8. "address2":"",
  9. "city":"",
  10. "zipCode":"",
  11. "state":"",
  12. "country":""
  13. }
  14. }

Create Organization

POST /api/orgs

Only works with Basic Authentication (username and password), see introduction.

Example Request:

  1. POST /api/orgs HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "name":"New Org."
  6. }

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:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {
  4. "orgId":"1",
  5. "message":"Organization created"
  6. }

Search all Organizations

GET /api/orgs

Only works with Basic Authentication (username and password), see introduction.

Example Request:

  1. GET /api/orgs HTTP/1.1
  2. Accept: application/json
  3. 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

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. [
  4. {
  5. "id":1,
  6. "name":"Main Org."
  7. }
  8. ]

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.

Example Request:

  1. PUT /api/orgs/1 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "name":"Main Org 2."
  6. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"Organization updated"}

Delete Organization

DELETE /api/orgs/:orgId

Only works with Basic Authentication (username and password), see introduction.

Example Request:

  1. DELETE /api/orgs/1 HTTP/1.1
  2. Accept: application/json

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"Organization deleted"}

Get Users in Organization

GET /api/orgs/:orgId/users

Only works with Basic Authentication (username and password), see introduction.

Example Request:

  1. GET /api/orgs/1/users HTTP/1.1
  2. Accept: application/json
  3. 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:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. [
  4. {
  5. "orgId":1,
  6. "userId":1,
  7. "email":"admin@mygraf.com",
  8. "login":"admin",
  9. "role":"Admin"
  10. }
  11. ]

Add User in Organization

POST /api/orgs/:orgId/users

Only works with Basic Authentication (username and password), see introduction.

Example Request:

  1. POST /api/orgs/1/users HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "loginOrEmail":"user",
  6. "role":"Viewer"
  7. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"User added to organization"}

Update Users in Organization

PATCH /api/orgs/:orgId/users/:userId

Only works with Basic Authentication (username and password), see introduction.

Example Request:

  1. PATCH /api/orgs/1/users/2 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "role":"Admin"
  6. }

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"Organization user updated"}

Delete User in Organization

DELETE /api/orgs/:orgId/users/:userId

Only works with Basic Authentication (username and password), see introduction.

Example Request:

  1. DELETE /api/orgs/1/users/2 HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json

Example Response:

  1. HTTP/1.1 200
  2. Content-Type: application/json
  3. {"message":"User removed from organization"}