Feature: specify grafana organisation for client

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 * Add methods `get_permissions_by_uid` and `update_permissions_by_uid` for dashboards.
   Thanks, @meyerder.
+* Add `GrafanaApi.organization_id` for targeting all requests to a Grafana organization
+  Thanks, @lilatomic
 
 
 ## 3.9.2 (2023-10-14)

README.md

@@ -135,6 +135,25 @@ grafana = GrafanaApi.from_env()
 Please note that, on top of the specific examples above, the object obtained by
 `credential` can be an arbitrary `requests.auth.AuthBase` instance.
 
+## Selecting Organizations
+
+If the Grafana API is authenticated as a user (for example, with HTTP Basic Authentication),
+it will use the user's current organization context.
+That context can be changed with the `GrafanaApi.user.switch_actual_user_organisation` function.
+
+```python
+grafana.user.switch_actual_user_organisation(1)
+```
+
+An instance of `GrafanaApi` can also be bound to a single organization with the `organization_id` parameter,
+ensuring that all requests will be made to that organization.
+This parameter will cause `GrafanaClient` to use the [X-Grafana-Org-Id header].
+
+```python
+grafana = GrafanaApi(..., organization_id=1)
+```
+
+API Tokens are bound to a single organization, so the `organization_id` parameter does not need to be specified.
 
 ## Timeout settings
 
@@ -294,5 +313,6 @@ follow the [development documentation].
 [future maintenance of `grafana_api`]: https://github.com/m0nhawk/grafana_api/issues/88
 [grafana_api]: https://github.com/m0nhawk/grafana_api
 [Grafana Admin API]: https://grafana.com/docs/grafana/latest/http_api/admin/
+[X-Grafana-Org-Id header]: https://grafana.com/docs/grafana/latest/developers/http_api/auth/#x-grafana-org-id-header
 [Grafana HTTP API reference]: https://grafana.com/docs/grafana/latest/http_api/
 [LICENSE]: https://github.com/panodata/grafana-client/blob/main/LICENSE

grafana_client/api.py

@@ -47,6 +47,7 @@ def __init__(
         verify=True,
         timeout=DEFAULT_TIMEOUT,
         user_agent: str = None,
+        organization_id: int = None,
     ):
         self.client = GrafanaClient(
             auth,
@@ -57,6 +58,7 @@ def __init__(
             verify=verify,
             timeout=timeout,
             user_agent=user_agent,
+            organization_id=organization_id,
         )
         self.url = None
         self.admin = Admin(self.client)

grafana_client/client.py

@@ -79,6 +79,7 @@ def __init__(
         verify=True,
         timeout=DEFAULT_TIMEOUT,
         user_agent: str = None,
+        organization_id: int = None,
     ):
         self.auth = auth
         self.verify = verify
@@ -111,6 +112,12 @@ def construct_api_url():
 
         self.s = requests.Session()
         self.s.headers["User-Agent"] = self.user_agent
+
+        self.organization_id = organization_id
+        if self.organization_id:
+            # orgId is defined in the openapi3 spec as an int64, but headers need to be a str
+            self.s.headers["X-Grafana-Org-Id"] = str(self.organization_id)
+
         if self.auth is not None:
             if isinstance(self.auth, requests.auth.AuthBase):
                 pass

test/test_grafana_client.py

@@ -39,6 +39,19 @@ def test_grafana_client_user_agent_custom(self):
         )
         self.assertEqual(grafana.client.s.headers["User-Agent"], "foobar/3000")
 
+    def test_grafana_client_no_org(self):
+        grafana = GrafanaApi(
+            ("admin", "admin"), host="localhost", url_path_prefix="", protocol="https", organization_id=None
+        )
+        self.assertNotIn("X-Grafana-Org-Id", grafana.client.s.headers)
+
+    def test_grafana_client_org(self):
+        org_id = 2
+        grafana = GrafanaApi(
+            ("admin", "admin"), host="localhost", url_path_prefix="", protocol="https", organization_id=org_id
+        )
+        self.assertEqual(grafana.client.s.headers["X-Grafana-Org-Id"], str(org_id))
+
     @patch("grafana_client.client.GrafanaClient.__getattr__")
     def test_grafana_client(self, mock_get):
         mock_get.return_value = Mock()