joshsmithxrm · ppds-docs-bot · Apr 27, 2026
diff --git a/docs/reference/libraries/Auth/AuthErrorCodes.md b/docs/reference/libraries/Auth/AuthErrorCodes.md
@@ -0,0 +1,47 @@
+<!-- Auto-generated by scripts/docs-gen/libs-reflect — edits will be overwritten on next release. -->
+
+# AuthErrorCodes
+
+- Namespace: `PPDS.Auth`
+- Assembly: `PPDS.Auth`
+- Kind: Class
+
+## Summary
+
+Hierarchical error codes used by PPDS.Auth's `PPDS.Auth.Credentials.AuthenticationException`.
+Values are stable strings consumers (CLI, MCP, RPC) can match programmatically.
+
+## Members
+
+### Fields
+
+#### BapApiError
+
+`string BapApiError`
+
+BAP API returned 429/5xx or another unexpected status.
+
+#### BapApiForbidden
+
+`string BapApiForbidden`
+
+BAP API returned 403 — SPN is not registered as a Power Platform management application.
+
+#### BapApiTimeout
+
+`string BapApiTimeout`
+
+BAP API call timed out.
+
+#### BapApiUnauthorized
+
+`string BapApiUnauthorized`
+
+BAP API returned 401 — token is invalid or expired.
+
+#### EnvironmentNotFound
+
+`string EnvironmentNotFound`
+
+Environment name was not found in BAP discovery results.
+
diff --git a/docs/reference/libraries/Auth/Cloud/CloudEndpoints.md b/docs/reference/libraries/Auth/Cloud/CloudEndpoints.md
@@ -56,6 +56,17 @@ Gets the MSAL Azure cloud instance for the specified cloud environment.
 
 - Returns: The Azure cloud instance.
 
+#### GetBapApiUrl
+
+`string GetBapApiUrl(CloudEnvironment cloud)`
+
+Gets the BAP (Business Application Platform) API base URL for the specified cloud environment.
+Used for environment discovery via the admin API when Global Discovery is not available.
+
+- Param `cloud`: The cloud environment.
+
+- Returns: The BAP API base URL.
+
 #### GetFlowPortalUrl
 
 `string GetFlowPortalUrl(CloudEnvironment cloud)`

diff --git a/docs/reference/libraries/Auth/Discovery/BapEnvironmentService.md b/docs/reference/libraries/Auth/Discovery/BapEnvironmentService.md
@@ -0,0 +1,69 @@
+<!-- Auto-generated by scripts/docs-gen/libs-reflect — edits will be overwritten on next release. -->
+
+# BapEnvironmentService
+
+- Namespace: `PPDS.Auth.Discovery`
+- Assembly: `PPDS.Auth`
+- Kind: Class
+- Implements: `IEnvironmentDiscoveryService`, `IDisposable`
+
+## Summary
+
+Discovers Dataverse environments via the BAP (Business Application Platform) admin API.
+Suitable for service principal authentication where Global Discovery is not available.
+
+## Members
+
+### Constructors
+
+#### BapEnvironmentService(HttpClient httpClient, string bapApiUrl, Func&lt;CancellationToken, Task&lt;string&gt;&gt; tokenProvider)
+
+`BapEnvironmentService(HttpClient httpClient, string bapApiUrl, Func<CancellationToken, Task<string>> tokenProvider)`
+
+Creates a new BapEnvironmentService.
+
+- Param `httpClient`: The HTTP client to use for API calls.
+
+- Param `bapApiUrl`: The BAP API base URL (e.g., https://api.bap.microsoft.com).
+
+- Param `tokenProvider`: A function that acquires a bearer token for the BAP API.
+
+
+### Methods
+
+#### DiscoverEnvironmentsAsync
+
+`Task<IReadOnlyList<DiscoveredEnvironment>> DiscoverEnvironmentsAsync(CancellationToken cancellationToken)`
+
+Discovers all environments accessible to the authenticated principal.
+
+- Param `cancellationToken`: Cancellation token.
+
+- Returns: Collection of discovered environments.
+
+#### Dispose
+
+`void Dispose()`
+
+*(inherited from `System.IDisposable.Dispose`)*
+
+#### FromProfileAsync
+
+`Task<BapEnvironmentService> FromProfileAsync(AuthProfile profile, ISecureCredentialStore credentialStore, CancellationToken cancellationToken)`
+
+Creates a BapEnvironmentService from an auth profile using MSAL confidential client.
+
+- Param `profile`: The auth profile (must use ClientSecret, CertificateFile, or CertificateStore).
+
+- Param `credentialStore`: Optional credential store for retrieving stored secrets.
+
+- Param `cancellationToken`: Cancellation token for the credential store lookup.
+
+- Returns: A new BapEnvironmentService instance. Caller must dispose.
+
+#### SupportsAuthMethod
+
+`bool SupportsAuthMethod(AuthMethod authMethod)`
+
+Returns whether the given auth method is supported by BAP discovery.
+
diff --git a/docs/reference/libraries/Auth/Discovery/DiscoveredEnvironment.md b/docs/reference/libraries/Auth/Discovery/DiscoveredEnvironment.md
@@ -41,6 +41,8 @@ Gets or sets the Power Platform environment ID.
 
 Gets the environment type as a string.
 Maps from Microsoft.Xrm.Sdk.Organization.OrganizationType enum values.
+Sentinels -1 / -2 are produced by BAP discovery (see BapEnvironmentService.MapEnvironmentSku)
+to distinguish a "Default" environment and an unrecognized SKU from a real Production org.
 
 #### FriendlyName
 

diff --git a/docs/reference/libraries/Auth/Discovery/EnvironmentResolutionResult.md b/docs/reference/libraries/Auth/Discovery/EnvironmentResolutionResult.md
@@ -16,7 +16,7 @@ Result of an environment resolution attempt.
 
 #### Failed
 
-`EnvironmentResolutionResult Failed(string errorMessage)`
+`EnvironmentResolutionResult Failed(string errorMessage, string errorCode)`
 
 Creates a failed result.
 
@@ -35,6 +35,13 @@ Creates a successful result.
 
 Gets the resolved environment info (null if failed).
 
+#### ErrorCode
+
+`string ErrorCode { get; set; }`
+
+Gets the structured error code carried from the underlying failure (null if successful or unknown).
+Values come from `PPDS.Auth.AuthErrorCodes`.
+
 #### ErrorMessage
 
 `string ErrorMessage { get; set; }`

diff --git a/docs/reference/libraries/Auth/Discovery/GlobalDiscoveryService.md b/docs/reference/libraries/Auth/Discovery/GlobalDiscoveryService.md
@@ -5,7 +5,7 @@
 - Namespace: `PPDS.Auth.Discovery`
 - Assembly: `PPDS.Auth`
 - Kind: Class
-- Implements: `IGlobalDiscoveryService`, `IDisposable`
+- Implements: `IEnvironmentDiscoveryService`, `IGlobalDiscoveryService`, `IDisposable`
 
 ## Summary
 

diff --git a/docs/reference/libraries/Auth/Discovery/IEnvironmentDiscoveryService.md b/docs/reference/libraries/Auth/Discovery/IEnvironmentDiscoveryService.md
@@ -0,0 +1,27 @@
+<!-- Auto-generated by scripts/docs-gen/libs-reflect — edits will be overwritten on next release. -->
+
+# IEnvironmentDiscoveryService
+
+- Namespace: `PPDS.Auth.Discovery`
+- Assembly: `PPDS.Auth`
+- Kind: Interface
+
+## Summary
+
+Common interface for services that discover Dataverse environments.
+Implemented by both Global Discovery Service (delegated user auth) and BAP API (service principal auth).
+
+## Members
+
+### Methods
+
+#### DiscoverEnvironmentsAsync
+
+`Task<IReadOnlyList<DiscoveredEnvironment>> DiscoverEnvironmentsAsync(CancellationToken cancellationToken)`
+
+Discovers all environments accessible to the authenticated principal.
+
+- Param `cancellationToken`: Cancellation token.
+
+- Returns: Collection of discovered environments.
+
diff --git a/docs/reference/libraries/Auth/Discovery/IGlobalDiscoveryService.md b/docs/reference/libraries/Auth/Discovery/IGlobalDiscoveryService.md
@@ -5,6 +5,7 @@
 - Namespace: `PPDS.Auth.Discovery`
 - Assembly: `PPDS.Auth`
 - Kind: Interface
+- Implements: `IEnvironmentDiscoveryService`
 
 ## Summary
 

diff --git a/docs/reference/libraries/Auth/Discovery/ResolutionMethod.md b/docs/reference/libraries/Auth/Discovery/ResolutionMethod.md
@@ -15,6 +15,12 @@ Method used to resolve an environment.
 
 ### Fields
 
+#### BapDiscovery
+
+`ResolutionMethod BapDiscovery`
+
+Resolved via BAP Environment Discovery (service principal).
+
 #### DirectConnection
 
 `ResolutionMethod DirectConnection`

diff --git a/docs/reference/libraries/Auth/_index.md b/docs/reference/libraries/Auth/_index.md
@@ -0,0 +1,87 @@
+<!-- Auto-generated by scripts/docs-gen/libs-reflect — edits will be overwritten on next release. -->
+
+# Auth reference
+
+## Interfaces
+
+| Type | Summary |
+|------|---------|
+| [ICredentialProvider](./Credentials/ICredentialProvider.md) | Provides authenticated ServiceClient instances for a specific auth method. |
+| [IEnvironmentDiscoveryService](./Discovery/IEnvironmentDiscoveryService.md) | Common interface for services that discover Dataverse environments. |
+| [IGlobalDiscoveryService](./Discovery/IGlobalDiscoveryService.md) | Service for discovering Dataverse environments via the Global Discovery Service. |
+| [IPowerPlatformTokenProvider](./Credentials/IPowerPlatformTokenProvider.md) | Provides access tokens for Power Platform REST APIs (Power Apps, Power Automate, etc.). |
+| [ISecureCredentialStore](./Credentials/ISecureCredentialStore.md) | Provides secure, platform-native credential storage for service principal secrets. |
+
+## Classes
+
+| Type | Summary |
+|------|---------|
+| [AmbiguousMatchException](./Discovery/AmbiguousMatchException.md) | Exception thrown when multiple environments match a given identifier. |
+| [AuthDebugLog](./AuthDebugLog.md) | Controls debug logging output for the auth library. |
+| [AuthErrorCodes](./AuthErrorCodes.md) | Hierarchical error codes used by PPDS.Auth's `PPDS.Auth.Credentials.AuthenticationException`. |
+| [AuthProfile](./Profiles/AuthProfile.md) | An authentication profile containing credentials and environment binding. |
+| [AuthenticationException](./Credentials/AuthenticationException.md) | Exception thrown when authentication fails. |
+| [AuthenticationOutput](./AuthenticationOutput.md) | Controls authentication status output for the auth library. |
+| [AzureDevOpsFederatedCredentialProvider](./Credentials/AzureDevOpsFederatedCredentialProvider.md) | Provides authentication using Azure DevOps OIDC (workload identity federation). |
+| [BapEnvironmentService](./Discovery/BapEnvironmentService.md) | Discovers Dataverse environments via the BAP (Business Application Platform) admin API. |
+| [CertificateFileCredentialProvider](./Credentials/CertificateFileCredentialProvider.md) | Provides authentication using a certificate file (PFX/P12). |
+| [CertificateStoreCredentialProvider](./Credentials/CertificateStoreCredentialProvider.md) | Provides authentication using a certificate from the Windows certificate store. |
+| [ClientSecretCredentialProvider](./Credentials/ClientSecretCredentialProvider.md) | Provides authentication using client ID and client secret (Service Principal). |
+| [CloudEndpoints](./Cloud/CloudEndpoints.md) | Provides endpoint URLs for different Azure cloud environments. |
+| [ConnectionResolver](./Pooling/ConnectionResolver.md) | Resolves profile names to authenticated connections. |
+| [CredentialProviderFactory](./Credentials/CredentialProviderFactory.md) | Factory for creating credential providers from auth profiles. |
+| [CredentialResult](./Credentials/CredentialResult.md) | Result of creating a credential provider. |
+| [DeviceCodeCredentialProvider](./Credentials/DeviceCodeCredentialProvider.md) | Provides authentication using device code flow. |
+| [DeviceCodeInfo](./Credentials/DeviceCodeInfo.md) | Information about a device code for authentication. |
+| [DiscoveredEnvironment](./Discovery/DiscoveredEnvironment.md) | Represents an environment discovered via the Global Discovery Service. |
+| [EnvironmentConfig](./Profiles/EnvironmentConfig.md) | User configuration for a specific Dataverse environment. |
+| [EnvironmentConfigCollection](./Profiles/EnvironmentConfigCollection.md) | Root object for environments.json — holds per-environment configs and custom type defaults. |
+| [EnvironmentConfigStore](./Profiles/EnvironmentConfigStore.md) | Manages persistent storage of environment configurations. |
+| [EnvironmentInfo](./Profiles/EnvironmentInfo.md) | Information about a Dataverse environment bound to a profile. |
+| [EnvironmentResolutionResult](./Discovery/EnvironmentResolutionResult.md) | Result of an environment resolution attempt. |
+| [EnvironmentResolutionService](./Discovery/EnvironmentResolutionService.md) | Service for resolving environments using a multi-layer strategy. |
+| [EnvironmentResolver](./Discovery/EnvironmentResolver.md) | Resolves an environment from a collection by various criteria. |
+| [EnvironmentVariableAuth](./EnvironmentVariableAuth.md) | Reads authentication configuration from environment variables for CI/CD scenarios. |
+| [GitHubFederatedCredentialProvider](./Credentials/GitHubFederatedCredentialProvider.md) | Provides authentication using GitHub Actions OIDC (workload identity federation). |
+| [GlobalDiscoveryService](./Discovery/GlobalDiscoveryService.md) | Service for discovering Dataverse environments via the Global Discovery Service. |
+| [InteractiveBrowserCredentialProvider](./Credentials/InteractiveBrowserCredentialProvider.md) | Provides authentication using interactive browser flow. |
+| [ManagedIdentityCredentialProvider](./Credentials/ManagedIdentityCredentialProvider.md) | Provides authentication using Azure Managed Identity. |
+| [NativeCredentialStore](./Credentials/NativeCredentialStore.md) | Provides secure, platform-native credential storage using OS credential managers. |
+| [PowerPlatformToken](./Credentials/PowerPlatformToken.md) | Represents an access token for Power Platform APIs. |
+| [PowerPlatformTokenProvider](./Credentials/PowerPlatformTokenProvider.md) | Provides access tokens for Power Platform REST APIs using MSAL. |
+| [ProfileCollection](./Profiles/ProfileCollection.md) | Collection of authentication profiles with active profile tracking. |
+| [ProfileConnectionSource](./Pooling/ProfileConnectionSource.md) | Connection source that creates ServiceClients from an authentication profile. |
+| [ProfileEncryption](./Profiles/ProfileEncryption.md) | Provides platform-specific encryption for sensitive profile data. |
+| [ProfilePaths](./Profiles/ProfilePaths.md) | Provides platform-specific paths for profile storage. |
+| [ProfileResolver](./Profiles/ProfileResolver.md) | Resolves which profile to use based on the priority order: |
+| [ProfileStore](./Profiles/ProfileStore.md) | Manages persistent storage of authentication profiles. |
+| [QuerySafetySettings](./Profiles/QuerySafetySettings.md) | Per-environment query safety settings. Stored in environment config JSON. |
+| [ServiceClientFactory](./ServiceClientFactory.md) | Factory for creating authenticated ServiceClient instances from profiles. |
+| [ServiceCollectionExtensions](./DependencyInjection/ServiceCollectionExtensions.md) | Extension methods for registering PPDS Auth services with dependency injection. |
+| [StoredCredential](./Credentials/StoredCredential.md) | Represents a credential stored in secure platform storage. |
+| [TokenCacheDetector](./Profiles/TokenCacheDetector.md) | Utility to detect the token cache type for the current platform. |
+| [TokenCacheManager](./Credentials/TokenCacheManager.md) | Manages token cache operations including clearing cached credentials. |
+| [UsernamePasswordCredentialProvider](./Credentials/UsernamePasswordCredentialProvider.md) | Provides authentication using username and password (ROPC flow). |
+
+## Records
+
+| Type | Summary |
+|------|---------|
+| [CachedTokenInfo](./Credentials/CachedTokenInfo.md) | Information about a cached token, retrieved without triggering authentication. |
+
+## Enums
+
+| Type | Summary |
+|------|---------|
+| [AuthMethod](./Profiles/AuthMethod.md) | Authentication method for a profile. |
+| [BypassPluginMode](./Profiles/BypassPluginMode.md) | Which plugin types to bypass during DML operations. |
+| [CloudEnvironment](./Cloud/CloudEnvironment.md) | Azure cloud environments for Dataverse authentication. |
+| [CrossEnvironmentDmlPolicy](./Profiles/CrossEnvironmentDmlPolicy.md) | Cross-environment DML policy. |
+| [DateTimeMode](./Profiles/DateTimeMode.md) | DateTime display mode for query results. |
+| [EnvironmentColor](./Profiles/EnvironmentColor.md) | Named colors for environment theming. |
+| [EnvironmentType](./Profiles/EnvironmentType.md) | Classification of Dataverse environment types. |
+| [PreAuthDialogResult](./Credentials/PreAuthDialogResult.md) | Result of the pre-authentication dialog shown before browser auth. |
+| [ProtectionLevel](./Profiles/ProtectionLevel.md) | Environment protection level determining DML behavior. |
+| [ResolutionMethod](./Discovery/ResolutionMethod.md) | Method used to resolve an environment. |
+| [TokenCacheType](./Profiles/TokenCacheType.md) | Token cache storage type. |
+