Group Attribute Sync HTTP API

This is documentation for the next version of Grafana. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana documentationbreadcrumb arrow Developersbreadcrumb arrow HTTP APIbreadcrumb arrow Group Attribute Sync HTTP API
Enterprise Open source

Group attribute sync API

The Group Attribute Sync API allows you to configure group attribute sync feature. This API is useful when you want to manage user roles based on group membership in an external system.

Note: Available in Grafana Enterprise and Grafana Cloud

Note

This feature is currently in private preview and behind the groupAttributeSync feature toggle. Please contact support to have this feature enabled.

List group mappings

GET /api/groupsync/groups

Required permissions

ActionScope
groupsync.mappings:readn/a

Example Request:

http 
GET /api/groupsync/groups HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

Example Response:

http 
HTTP/1.1 200
Content-Type: application/json

[
  {
    "groups": [
        {
            "groupID": "group 1",
            "mappings": {
                "1": {
                    "roles": [
                        "fixed_nzVQoNSDSn0fg1MDgO6XnZX2RZI",
                        "my_custom_role",
                    ]
                }
            }
        },
        {
            "groupID": "group 2",
            "mappings": {
                "1": {
                    "roles": [
                        "another_role",
                    ]
                }
            }
        }
    ],
    "total": 2
  }
]

Status Codes:

  • 200 - Ok
  • 400 - Bad request
  • 401 - Unauthorized
  • 403 - Permission denied
  • 500 - Internal server error

Create group mappings

POST /api/groupsync/groups/:groupID

Required permissions

ActionScope
groupsync.mappings:writen/a

Example Request:

http 
POST /api/groupsync/groups/my_group_id HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

{
    "roles": [
        "fixed_nzVQoNSDSn0fg1MDgO6XnZX2RZI",
        "my_custom_role_uid"
    ]
}

Example Response:

http 
HTTP/1.1 200
Content-Type: application/json

{
    "message": "Group mappings created."
}

Status Codes:

  • 201 - Ok
  • 400 - Bad request
  • 401 - Unauthorized
  • 403 - Permission denied
  • 500 - Internal server error

Update group mappings

PUT /api/groupsync/groups/:groupID

This endpoint will replace the existing mappings for the group with the new mappings provided in the request.

Required permissions

ActionScope
groupsync.mappings:writen/a

Example Request:

http 
PUT /api/groupsync/groups/my_group_id HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

{
    "roles": [
        "fixed_nzVQoNSDSn0fg1MDgO6XnZX2RZI",
        "my_custom_role_uid"
    ]
}

Example Response:

http 
HTTP/1.1 200
Content-Type: application/json

{
    "message": "Group mappings set."
}

Status Codes:

  • 201 - Ok
  • 400 - Bad request
  • 401 - Unauthorized
  • 403 - Permission denied
  • 500 - Internal server error

Remove group mappings

DELETE /api/groupsync/groups/:groupID

Required permissions

ActionScope
groupsync.mappings:writen/a

Example Request:

http 
DELETE /api/groupsync/groups/my_group_id HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt

Status Codes:

  • 204 - Ok
  • 400 - Bad request
  • 401 - Unauthorized
  • 403 - Permission denied
  • 500 - Internal server error