Merge pull request #5356 from grafana/dev

v1.13.10

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 \

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

@@ -30,6 +30,8 @@ For more details about specific fields of a webhook, refer to [Outgoing webhooks
 
 ## List webhooks
 
+**Required permission**: `grafana-oncall-app.outgoing-webhooks:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/webhooks/" \
   --request GET \
@@ -75,6 +77,8 @@ The above command returns JSON structured in the following way:
 
 ## Get webhook
 
+**Required permission**: `grafana-oncall-app.outgoing-webhooks:read`
+
 ```shell
 curl "{{API_URL}}/api/v1/webhooks/{{WEBHOOK_UID}}/" \
   --request GET \
@@ -108,6 +112,8 @@ The above command returns JSON structured in the following way:
 
 ## Create webhook
 
+**Required permission**: `grafana-oncall-app.outgoing-webhooks:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/webhooks/" \
   --request POST \
@@ -167,6 +173,8 @@ The above command returns JSON structured in the following way:
 
 ## Update webhook
 
+**Required permission**: `grafana-oncall-app.outgoing-webhooks:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/webhooks/{{WEBHOOK_UID}}/" \
   --request PUT \
@@ -201,6 +209,8 @@ The above command returns JSON structured in the following way:
 
 ## Delete webhook
 
+**Required permission**: `grafana-oncall-app.outgoing-webhooks:write`
+
 ```shell
 curl "{{API_URL}}/api/v1/webhooks/{{WEBHOOK_UID}}/" \
   --request DELETE \

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

@@ -14,6 +14,8 @@ refs:
 
 ## Post a personal notification rule
 
+**Required permission**: `grafana-oncall-app.user-settings:write` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/personal_notification_rules/" \
   --request POST \
@@ -51,6 +53,8 @@ The above command returns JSON structured in the following way:
 
 ## Get personal notification rule
 
+**Required permission**: `grafana-oncall-app.user-settings:read` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/personal_notification_rules/ND9EHN5LN1DUU/" \
   --request GET \
@@ -77,6 +81,8 @@ The above command returns JSON structured in the following way:
 
 ## List personal notification rules
 
+**Required permission**: `grafana-oncall-app.user-settings:read` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/personal_notification_rules/" \
   --request GET \
@@ -141,6 +147,8 @@ The following available filter parameters should be provided as `GET` arguments:
 
 ## Delete a personal notification rule
 
+**Required permission**: `grafana-oncall-app.user-settings:write` (user authentication only)
+
 ```shell
 curl "{{API_URL}}/api/v1/personal_notification_rules/NWAL6WFJNWDD8/" \
   --request DELETE \