docs(xaa): document the read-only project-level audience on the XAA load response (#1677)

load_xaa_settings / load_all_xaa_settings return the audience a requesting application
must present in its ID-JAG token. It is project-level and names no tenant - the IdP
sends the tenant in the token's aud_tenant claim - so document it as part of the
returned shape rather than leaving callers to build the value by hand.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dorsha

descope/management/sso_settings.py

@@ -584,7 +584,10 @@ def load_xaa_settings(
 
         Return value (dict):
         Containing the loaded XAA settings (ssoId, enabled, settings, groupsMapping, defaultSSORoles,
-        fgaMappings, groupsPriority, groupPriorityEnabled, allowOverrideRoles).
+        fgaMappings, groupsPriority, groupPriorityEnabled, allowOverrideRoles, audience).
+        audience is read-only: the project-level audience a requesting application must present in its
+        ID-JAG token. It carries no tenant segment - it equals the issuer the project publishes - so the
+        identity provider must send the tenant id in the token's aud_tenant claim.
 
         Raise:
         AuthException: raised if load operation fails

descope/management/sso_settings_async.py

@@ -316,7 +316,10 @@ async def load_xaa_settings(
         sso_id (str): Optional, the SSO configuration id (for multi-SSO). Omit for the default SSO configuration.
 
         Return value (dict):
-        Containing the loaded XAA settings.
+        Containing the loaded XAA settings, including the read-only project-level audience a requesting
+        application must present in its ID-JAG token. The audience carries no tenant segment - it equals
+        the issuer the project publishes - so the identity provider must send the tenant id in the
+        token's aud_tenant claim.
 
         Raise:
         AuthException: raised if load operation fails

tests/management/test_sso_settings.py

@@ -482,7 +482,7 @@ async def test_load_xaa_settings(self, client_factory):
 
         # Test success flow (with ssoId)
         resp_data = json.loads(
-            """{"ssoId": "sso-1", "enabled": true, "settings": {"issuers": {"https://issuer.example.com": {"jwksUri": "https://issuer.example.com/jwks", "signAlgorithm": "RS256"}}}, "groupsMapping": [{"role": {"id": "r1", "name": "role1"}, "groups": ["g1"]}], "defaultSSORoles": ["aa"], "groupPriorityEnabled": true, "allowOverrideRoles": true}"""
+            """{"ssoId": "sso-1", "enabled": true, "settings": {"issuers": {"https://issuer.example.com": {"jwksUri": "https://issuer.example.com/jwks", "signAlgorithm": "RS256"}}}, "groupsMapping": [{"role": {"id": "r1", "name": "role1"}, "groups": ["g1"]}], "defaultSSORoles": ["aa"], "groupPriorityEnabled": true, "allowOverrideRoles": true, "audience": "https://api.descope.com/v1/apps/P1"}"""
         )
         with client.mock_mgmt_get(make_response(resp_data)) as mock_get:
             resp = await client.invoke(client.mgmt.sso.load_xaa_settings("tenant-id", "sso-1"))
@@ -493,6 +493,8 @@ async def test_load_xaa_settings(self, client_factory):
                 == "https://issuer.example.com/jwks"
             )
             assert resp.get("groupsMapping")[0]["role"]["name"] == "role1"
+            # Read-only, project-level: no tenant segment - the tenant travels in the aud_tenant claim.
+            assert resp.get("audience") == "https://api.descope.com/v1/apps/P1"
             assert_http_called(
                 mock_get,
                 client.mode,