From d83288b8c562dc7c9624ac917252267977ba9264 Mon Sep 17 00:00:00 2001
From: Mihai Doarna <mihai.doarna@grafana.com>
Date: Fri, 31 May 2024 11:22:54 +0300
Subject: [PATCH] Docs: Improve the SSO settings API docs (#87599)

* improve SSO settings API docs

* address feedback
---
 .../developers/http_api/sso-settings.md       | 26 +++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/docs/sources/developers/http_api/sso-settings.md b/docs/sources/developers/http_api/sso-settings.md
index c7c8a343a3a..cb426373485 100644
--- a/docs/sources/developers/http_api/sso-settings.md
+++ b/docs/sources/developers/http_api/sso-settings.md
@@ -23,10 +23,17 @@ title: SSO Settings API
 > If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.
 
 {{% admonition type="note" %}}
-Available in Public Preview in Grafana 10.4 and on Grafana Cloud behind the `ssoSettingsApi` feature toggle.
+Available since Grafana 11. SAML support is in public preview behind the `ssoSettingsSAML` feature flag.
 {{% /admonition %}}
 
-The API can be used to create, update, delete, get, and list SSO Settings.
+The API can be used to create, update, delete, get, and list SSO Settings for OAuth2 and SAML.
+
+The settings managed by this API are stored in the database and override
+[settings from other sources]({{< relref "../../setup-grafana/configure-security/configure-authentication" >}})
+(arguments, environment variables, settings file, etc).
+Therefore, every time settings for a specific provider are removed or reset to the default settings at runtime,
+the settings are inherited from the other sources in the reverse order of precedence
+(`arguments > environment variables > settings file`).
 
 ## List SSO Settings
 
@@ -34,6 +41,8 @@ The API can be used to create, update, delete, get, and list SSO Settings.
 
 Lists the SSO Settings for all providers.
 
+The providers or SSO keys that are not managed by this API are retrieved from the other sources (settings file, environment variables, default values).
+
 **Required permissions**
 
 See note in the [introduction]({{< ref "#sso-settings" >}}) for an explanation.
@@ -99,6 +108,8 @@ Status Codes:
 
 Gets the SSO Settings for a provider.
 
+The SSO keys that are not managed by this API are retrieved from the other sources (settings file, environment variables, default values).
+
 **Required permissions**
 
 See note in the [introduction]({{< ref "#sso-settings" >}}) for an explanation.
@@ -151,6 +162,17 @@ Status Codes:
 
 Updates the SSO Settings for a provider.
 
+When you submit new settings for a provider via API,
+Grafana verifies whether the given settings are allowed and valid.
+If they are, then Grafana stores the settings in the database and reloads
+Grafana services with no need to restart the instance.
+
+{{% admonition type="note" %}}
+If you run Grafana in high availability mode, configuration changes
+may not get applied to all Grafana instances immediately. You may need
+to wait a few minutes for the configuration to propagate to all Grafana instances.
+{{% /admonition %}}
+
 **Required permissions**
 
 See note in the [introduction]({{< ref "#sso-settings" >}}) for an explanation.