From 21242f0ed06ccdc4c368959064c17fefc4bfb6ce Mon Sep 17 00:00:00 2001
From: Hector Hernandez <39923391+hectorhdzg@users.noreply.github.com>
Date: Wed, 6 May 2026 13:06:09 -0700
Subject: [PATCH 1/2] docs: add auth scopes breaking change to A365 migration
 guide

---
 MIGRATION_A365.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/MIGRATION_A365.md b/MIGRATION_A365.md
index 9576283c..4dfc5525 100644
--- a/MIGRATION_A365.md
+++ b/MIGRATION_A365.md
@@ -427,6 +427,43 @@ the filter logic to any criteria (span name, attributes, etc.).
 | `ENABLE_OTLP_EXPORTER` | `OTEL_EXPORTER_OTLP_ENDPOINT` | Use standard OTel env var instead |
 | `ENABLE_OBSERVABILITY` | `ENABLE_OBSERVABILITY` | Same — master switch for A365 scope classes to emit spans |
 
+## Auth Scopes — Breaking Change
+
+> **⚠️ Breaking change:** The default observability authentication scope changed
+> from `https://api.powerplatform.com/.default` (old A365 SDK) to
+> `api://9b975845-388f-4429-889e-eab1ef63949c/.default`. If you previously
+> hardcoded the old scope, you will get auth failures after migration. You must
+> also grant the `Agent365.Observability.OtelWrite` permission — see
+> [HTTP 403 after upgrading](#http-403-after-upgrading).
+
+The correct scope depends on your authentication flow:
+
+| Flow | Scope |
+|------|-------|
+| Default / OBO (on-behalf-of) | `api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite` |
+| S2S (service-to-service) | `api://9b975845-388f-4429-889e-eab1ef63949c` |
+
+Do **not** hardcode scope strings. Instead, use the runtime helper to get the
+correct scope automatically:
+
+```python
+from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope
+
+scope = get_observability_authentication_scope()
+```
+
+If you need to override the scope for testing, use the
+`a365_observability_scope_override` kwarg or the
+`A365_OBSERVABILITY_SCOPE_OVERRIDE` environment variable:
+
+```bash
+# Linux / macOS
+export A365_OBSERVABILITY_SCOPE_OVERRIDE="api://test/.default"
+
+# Windows PowerShell
+$env:A365_OBSERVABILITY_SCOPE_OVERRIDE = "api://test/.default"
+```
+
 ## Full Migration Example
 
 ```python

From f599f3b6e8d339cdb05fda1f39acd705695e1e80 Mon Sep 17 00:00:00 2001
From: Hector Hernandez <39923391+hectorhdzg@users.noreply.github.com>
Date: Wed, 6 May 2026 13:33:58 -0700
Subject: [PATCH 2/2] docs: fix auth scope to match PROD_OBSERVABILITY_SCOPE,
 fix helper return type

---
 MIGRATION_A365.md | 17 +++++------------
 1 file changed, 5 insertions(+), 12 deletions(-)

diff --git a/MIGRATION_A365.md b/MIGRATION_A365.md
index 4dfc5525..3ca8e02d 100644
--- a/MIGRATION_A365.md
+++ b/MIGRATION_A365.md
@@ -431,17 +431,10 @@ the filter logic to any criteria (span name, attributes, etc.).
 
 > **⚠️ Breaking change:** The default observability authentication scope changed
 > from `https://api.powerplatform.com/.default` (old A365 SDK) to
-> `api://9b975845-388f-4429-889e-eab1ef63949c/.default`. If you previously
-> hardcoded the old scope, you will get auth failures after migration. You must
-> also grant the `Agent365.Observability.OtelWrite` permission — see
-> [HTTP 403 after upgrading](#http-403-after-upgrading).
-
-The correct scope depends on your authentication flow:
-
-| Flow | Scope |
-|------|-------|
-| Default / OBO (on-behalf-of) | `api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite` |
-| S2S (service-to-service) | `api://9b975845-388f-4429-889e-eab1ef63949c` |
+> `api://9b975845-388f-4429-889e-eab1ef63949c/Agent365.Observability.OtelWrite`.
+> If you previously hardcoded the old scope, you will get auth failures after
+> migration. You must also grant the `Agent365.Observability.OtelWrite`
+> permission — see [HTTP 403 after upgrading](#http-403-after-upgrading).
 
 Do **not** hardcode scope strings. Instead, use the runtime helper to get the
 correct scope automatically:
@@ -449,7 +442,7 @@ correct scope automatically:
 ```python
 from microsoft.opentelemetry.a365.runtime import get_observability_authentication_scope
 
-scope = get_observability_authentication_scope()
+scopes = get_observability_authentication_scope()  # returns list[str]
 ```
 
 If you need to override the scope for testing, use the