Organization API

    GET /api/org/

    Example Request:

    Example Response:

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

    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 for an explanation.

    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
    4. [
    5.   {
    6.     "orgId": 1,
    7.     "userId": 1,
    8.     "email": "admin@localhost",
    9.     "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56",
    10.     "login": "admin",
    11.     "role": "Admin",
    12.     "lastSeenAt": "2019-08-09T11:02:49+02:00",
    13.     "lastSeenAtAge": "< 1m"
    14.   }
    15. ]

    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.

    Example Request:

    1. GET /api/org/users/lookup 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
    4. [
    5.   {
    6.     "userId": 1,
    7.     "login": "admin",
    8.     "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
    9.   }
    10. ]

    Updates the given user

    PATCH /api/org/users/:userId

    Required permissions

    See note in the introduction for an explanation.

    ActionScope
    org.users.role:updateusers:*

    Example Request:

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

    Example Response:

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

    Delete user in current organization

    DELETE /api/org/users/:userId

    Required permissions

    See note in the for an explanation.

    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
    4. {"message":"User removed from 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
    6. {
    7.   "name":"Main Org."
    8. }

    Example Response:

    Add a new user to the current organization

    POST /api/org/users

    Required permissions

    See note in the for an explanation.

    ActionScope
    org.users:addusers:*

    Example Request:

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

    Example Response:

    1. HTTP/1.1 200
    2. Content-Type: application/json
    4. {"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.

    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
    4. {
    5.   "id":1,
    6.   "name":"Main Org.",
    7.   "address":{
    8.     "address1":"",
    9.     "address2":"",
    10.     "city":"",
    11.     "zipCode":"",
    12.     "state":"",
    13.     "country":""
    14.   }
    15. }

    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
    4. {
    5.   "id":1,
    6.   "name":"Main Org.",
    7.   "address":{
    8.     "address1":"",
    9.     "address2":"",
    10.     "city":"",
    11.     "zipCode":"",
    12.     "state":"",
    13.     "country":""
    14.   }
    15. }

    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 value users.allow_org_create to true in ini file

    Example Response:

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

    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

    Default value for the perpage parameter is 1000 and for the page parameter is 0.

    Example Response:

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

    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 .

    Example Response:

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

    Delete Organization

    DELETE /api/orgs/:orgId

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

    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
    4. {"message":"Organization deleted"}

    Get Users in Organization

    GET /api/orgs/:orgId/users

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

    Required permissions

    See note in the for an explanation.

    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.

    Required permissions

    See note in the introduction for an explanation.

    ActionScope
    org.users:addusers:*

    Example Request:

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

    Example Response:

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

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

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

    Required permissions

    See note in the introduction for an explanation.

    Example Request:

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

    Example Response:

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

    Delete User in Organization

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

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

    Required permissions

    See note in the introduction for an explanation.

    ActionScope
    org.users:removeusers:*

    Example Request:

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