Merge branch 'dev' into vadimkerr/iem-html

docs/sources/manage/notify/ms-teams/index.md

@@ -23,6 +23,10 @@ aliases:
 
 # MS Teams integration for Grafana OnCall
 
+{{< admonition type="note" >}}
+This integration is available exclusively on Grafana Cloud.
+{{< /admonition >}}
+
 The Microsoft Teams integration for Grafana OnCall embeds your MS Teams channels directly into your incident response
 workflow to help your team focus on alert resolution.
 
@@ -32,33 +36,38 @@ acknowledge, unacknowledge, resolve, and silence.
 
 ## Before you begin
 
-> NOTE: **This integration is available to Grafana Cloud instances of Grafana OnCall only.**
-
 The following is required to connect to Microsoft Teams to Grafana OnCall:
 
 - You must have Admin permissions in your Grafana Cloud instance.
 - You must have Owner permissions in Microsoft Teams.
 - Install the Grafana IRM app from the [Microsoft Marketplace](https://appsource.microsoft.com/en-us/product/office/WA200004307).
 
-## Install Microsoft Teams integration for Grafana OnCall
+## Connect Microsoft Teams with Grafana OnCall
+
+{{< admonition type="note" >}}
+A Microsoft Teams workspace can only be connected to one Grafana Cloud instance and cannot be connected to multiple environments.
+{{< /admonition >}}
+
+To connect Microsoft Teams with Grafana OnCall:
 
-1. Navigate to **Settings** tab in Grafana OnCall.
+1. In Grafana OnCall, open **Settings** and click **Chat Ops**.
 1. From the **Chat Ops** tab, select **Microsoft Teams** in the side menu.
-1. Follow the steps provided to connect to your Teams channels, then click **Done**.
-1. To add additional teams and channels click **+Add MS Teams channel** again and repeat step 3 as needed.
+1. Follow the in-app instructions to add the Grafana IRM app to your Teams workspace.
+1. After your workspace is connected, copy and paste the provided code into a Teams channel to add the IRM bot, then click **Done**.
+1. To add additional channels click **+Add MS Teams channel** and repeat step 3 as needed.
 
 ## Post-install configuration for Microsoft Teams integration
 
 Configure the following settings to ensure Grafana OnCall alerts are routed to the intended Teams channels and users:
 
-- Set a default channel from the list of connected MS Teams channels. This is where alerts will be sent unless otherwise
-  specified in escalation chains.
+- Set a default channel from the list of connected MS Teams channels.
+This is where alerts will be sent unless otherwise specified in escalation chains.
 - Ensure all users verify their MS Teams account in their Grafana OnCall user profile.
 
 ### Connect Microsoft Teams user to Grafana OnCall
 
-1. From the **Users** tab in Grafana OnCall, click **View my profile**.
-1. In the **User Info** tab, navigate to **Microsoft Teams username**, click **Connect**.
+1. From the **Users** tab of Grafana OnCall, click **View my profile**.
+1. In the **User Info** tab, locate **Notification channels**, **MS Teams**, and click **Connect account**.
 1. Follow the steps provided to connect your Teams user.
 1. Navigate back to your Grafana OnCall profile and verify that your Microsoft Teams account is linked to your Grafana
    OnCall user.

docs/sources/oncall-api-reference/_index.md

@@ -29,7 +29,7 @@ To authorize, use the **Authorization** header:
 
 ```shell
 # With shell, you can just pass the correct header with each request
-curl "api_endpoint_here" --header "Authorization: "api_key_here""
+curl "api_endpoint_here" --header "Authorization: <api_key_here>"
 ```
 
 Grafana OnCall uses API keys to allow access to the API. You can request a new OnCall API key in OnCall -> Settings page.
@@ -39,6 +39,19 @@ request a different API key.
 
 The endpoint refers to the OnCall Application endpoint and can be found on the OnCall -> Settings page as well.
 
+### Authentication using Service Account tokens
+
+It is also possible to use a [service account token](https://grafana.com/docs/grafana/latest/administration/service-accounts/#service-account-tokens)
+to authenticate instead of an OnCall access token. In this case you will also need to provide a
+header (`X-Grafana-URL`) pointing to your Grafana stack:
+
+```shell
+# With shell, you can just pass the correct header with each request
+curl "api_endpoint_here" --header "Authorization: <service account token>" --header "X-Grafana-URL: <your stack URL>"
+```
+
+Service accounts allow you to set explicit permissions for tokens as well as expire and/or disable them if needed.
+
 ## Pagination
 
 List endpoints such as List Integrations or List Alert Groups return multiple objects.

docs/sources/oncall-api-reference/alertgroups.md

@@ -14,6 +14,8 @@ refs:
 
 ## List alert groups
 
+**Required permission**: `grafana-oncall-app.alert-groups:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/" \
   --request GET \
@@ -97,6 +99,8 @@ These available filter parameters should be provided as `GET` arguments:
 
 ## Alert group details
 
+**Required permission**: `grafana-oncall-app.alert-groups:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1" \
   --request GET \
@@ -109,6 +113,8 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1" \
 
 ## Acknowledge an alert group
 
+**Required permission**: `grafana-oncall-app.alert-groups:write` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/acknowledge" \
   --request POST \
@@ -121,6 +127,8 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/acknowledge" \
 
 ## Unacknowledge an alert group
 
+**Required permission**: `grafana-oncall-app.alert-groups:write` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unacknowledge" \
   --request POST \
@@ -133,6 +141,8 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unacknowledge" \
 
 ## Resolve an alert group
 
+**Required permission**: `grafana-oncall-app.alert-groups:write` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/resolve" \
   --request POST \
@@ -145,6 +155,8 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/resolve" \
 
 ## Unresolve an alert group
 
+**Required permission**: `grafana-oncall-app.alert-groups:write` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unresolve" \
   --request POST \
@@ -157,6 +169,8 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unresolve" \
 
 ## Silence an alert group
 
+**Required permission**: `grafana-oncall-app.alert-groups:write` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/silence" \
   --request POST \
@@ -177,6 +191,8 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/silence" \
 
 ## Unsilence an alert group
 
+**Required permission**: `grafana-oncall-app.alert-groups:write` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unsilence" \
   --request POST \
@@ -189,6 +205,8 @@ curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/unsilence" \
 
 ## Delete an alert group
 
+**Required permission**: `grafana-oncall-app.alert-groups:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/" \
   --request DELETE \

docs/sources/oncall-api-reference/alerts.md

@@ -14,6 +14,8 @@ refs:
 
 ## List Alerts
 
+**Required permission**: `grafana-oncall-app.alert-groups:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/alerts/" \
   --request GET \

docs/sources/oncall-api-reference/escalation.md

@@ -22,6 +22,8 @@ refs:
 
 # Escalation HTTP API
 
+**Required permission**: `grafana-oncall-app.alert-groups:direct-paging` (user authentication only)
+
 See [Manual paging integration](ref:manual-paging) for more background on how escalating to a team or user(s) works.
 
 ## Escalate to a set of users

docs/sources/oncall-api-reference/escalation_chains.md

@@ -14,6 +14,8 @@ refs:
 
 ## Create an escalation chain
 
+**Required permission**: `grafana-oncall-app.escalation-chains:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_chains/" \
   --request POST \
@@ -45,6 +47,8 @@ The above command returns JSON structured in the following way:
 
 ## Get an escalation chain
 
+**Required permission**: `grafana-oncall-app.escalation-chains:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/" \
   --request GET \
@@ -68,6 +72,8 @@ The above command returns JSON structured in the following way:
 
 ## List escalation chains
 
+**Required permission**: `grafana-oncall-app.escalation-chains:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_chains/" \
   --request GET \
@@ -103,6 +109,8 @@ The above command returns JSON structured in the following way:
 
 ## Delete an escalation chain
 
+**Required permission**: `grafana-oncall-app.escalation-chains:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/" \
   --request DELETE \

docs/sources/oncall-api-reference/escalation_policies.md

@@ -14,6 +14,8 @@ refs:
 
 ## Create an escalation policy
 
+**Required permission**: `grafana-oncall-app.escalation-chains:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/" \
   --request POST \
@@ -61,6 +63,8 @@ The above command returns JSON structured in the following way:
 
 ## Get an escalation policy
 
+**Required permission**: `grafana-oncall-app.escalation-chains:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
   --request GET \
@@ -82,6 +86,8 @@ The above command returns JSON structured in the following way:
 
 ## Update an escalation policy
 
+**Required permission**: `grafana-oncall-app.escalation-chains:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
   --request PUT \
@@ -115,6 +121,8 @@ The above command returns JSON structured in the following way:
 
 ## List escalation policies
 
+**Required permission**: `grafana-oncall-app.escalation-chains:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/" \
   --request GET \
@@ -163,6 +171,8 @@ The following available filter parameter should be provided as a `GET` argument:
 
 ## Delete an escalation policy
 
+**Required permission**: `grafana-oncall-app.escalation-chains:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
   --request DELETE \

docs/sources/oncall-api-reference/integrations.md

@@ -23,6 +23,8 @@ refs:
 
 ## Create an integration
 
+**Required permission**: `grafana-oncall-app.integrations:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/integrations/" \
   --request POST \
@@ -102,6 +104,8 @@ For example, to learn how to integrate Grafana OnCall with Alertmanager refer to
 
 ## Get integration
 
+**Required permission**: `grafana-oncall-app.integrations:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
   --request GET \
@@ -177,6 +181,8 @@ This endpoint retrieves an integration. Integrations are sources of alerts and a
 
 ## List integrations
 
+**Required permission**: `grafana-oncall-app.integrations:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/integrations/" \
   --request GET \
@@ -262,6 +268,8 @@ The above command returns JSON structured in the following way:
 
 ## Update integration
 
+**Required permission**: `grafana-oncall-app.integrations:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
   --request PUT \
@@ -339,6 +347,8 @@ The above command returns JSON structured in the following way:
 
 ## Delete integration
 
+**Required permission**: `grafana-oncall-app.integrations:write`
+
 Deleted integrations will stop recording new alerts from monitoring. Integration removal won't trigger removal of
 related alert groups or alerts.
 

docs/sources/oncall-api-reference/on_call_shifts.md

@@ -14,6 +14,8 @@ refs:
 
 ## Create an OnCall shift
 
+**Required permission**: `grafana-oncall-app.schedules:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/" \
   --request POST \
@@ -77,6 +79,8 @@ For more information about recurrence rules, refer to [RFC 5545](https://tools.i
 
 ## Get OnCall shifts
 
+**Required permission**: `grafana-oncall-app.schedules:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
   --request GET \
@@ -106,6 +110,8 @@ The above command returns JSON structured in the following way:
 
 ## List OnCall shifts
 
+**Required permission**: `grafana-oncall-app.schedules:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/" \
   --request GET \
@@ -169,6 +175,8 @@ The following available filter parameters should be provided as `GET` arguments:
 
 ## Update OnCall shift
 
+**Required permission**: `grafana-oncall-app.schedules:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
   --request PUT \
@@ -208,6 +216,8 @@ The above command returns JSON structured in the following way:
 
 ## Delete OnCall shift
 
+**Required permission**: `grafana-oncall-app.schedules:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/on_call_shifts/OH3V5FYQEYJ6M/" \
   --request DELETE \

docs/sources/oncall-api-reference/organizations.md

@@ -14,6 +14,8 @@ refs:
 
 ## Get an organization
 
+**Required permission**: `grafana-oncall-app.other-settings:read`
+
 This endpoint retrieves the organization object.
 
 ```shell
@@ -41,6 +43,8 @@ The above command returns JSON structured in the following way:
 
 ## List Organizations
 
+**Required permission**: `grafana-oncall-app.other-settings:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/organizations/" \
   --request GET \