doc: Updated the Examples.md file with the new CredentialsManagerExceptions

EXAMPLES.md

@@ -279,6 +279,21 @@ if (DPoP.isNonceRequiredError(response)) {
 }
 ```
 
+When using DPoP with `CredentialsManager` or `SecureCredentialsManager`, the `AuthenticationAPIClient` passed to the credentials manager **must** also have DPoP enabled. Otherwise, token refresh requests will be sent without the DPoP proof and the SDK will throw a `CredentialsManagerException.DPOP_NOT_CONFIGURED` error.
+
+```kotlin
+
+val auth0 = Auth0.getInstance("YOUR_CLIENT_ID", "YOUR_DOMAIN")
+val apiClient = AuthenticationAPIClient(auth0).useDPoP(context)  // DPoP enabled
+val storage = SharedPreferencesStorage(context)
+val manager = CredentialsManager(apiClient, storage)
+
+WebAuthProvider
+    .useDPoP()
+    .login(auth0)
+    .start(context, callback)
+```
+
 On logout, you should call `DPoP.clearKeyPair()` to delete the user's key pair from the Keychain.
 
 ```kotlin
@@ -292,7 +307,7 @@ WebAuthProvider.logout(account)
 
             })
 ```
-> [!NOTE]  
+> [!NOTE]
 > DPoP is supported only on Android version 6.0 (API level 23) and above. Trying to use DPoP in any older versions will result in an exception.
 
 ## Authentication API
@@ -1661,11 +1676,21 @@ val auth0 = Auth0.getInstance("YOUR_CLIENT_ID", "YOUR_DOMAIN")
 val apiClient = AuthenticationAPIClient(auth0).useDPoP(this)
 val storage = SharedPreferencesStorage(this)
 val manager = SecureCredentialsManager(apiClient, this, auth0, storage)
+```
+
+Similarly, for `CredentialsManager`:
 
+```kotlin
+val auth0 = Auth0.getInstance("YOUR_CLIENT_ID", "YOUR_DOMAIN")
+val apiClient = AuthenticationAPIClient(auth0).useDPoP(this)
+val storage = SharedPreferencesStorage(this)
+val manager = CredentialsManager(apiClient, storage)
 ```
 
+> [!IMPORTANT]
+> When credentials are DPoP-bound, the SDK validates the DPoP key state before each token refresh. If the DPoP key pair is lost, the SDK will throw `CredentialsManagerException.DPOP_KEY_MISSING` and the user must re-authenticate. If the key pair has changed since the credentials were saved, the SDK will throw `CredentialsManagerException.DPOP_KEY_MISMATCH`. If the `AuthenticationAPIClient` was not configured with `useDPoP()`, the SDK will throw `CredentialsManagerException.DPOP_NOT_CONFIGURED`.
 
-> [!NOTE]  
+> [!NOTE]
 > DPoP is supported only on Android version 6.0 (API level 23) and above. Trying to use DPoP in any older versions will result in an exception.
 
 
@@ -2550,24 +2575,42 @@ In the event that something happened while trying to save or retrieve the creden
 - Tokens have expired but no `refresh_token` is available to perform a refresh credentials request.
 - Device's Lock Screen security settings have changed (e.g. the PIN code was changed). Even when `hasCredentials` returns true, the encryption keys will be deemed invalid and until `saveCredentials` is called again it won't be possible to decrypt any previously existing content, since they keys used back then are not the same as the new ones.
 - Device is not compatible with some of the algorithms required by the `SecureCredentialsManager` class. This is considered a catastrophic event and might happen when the OEM has modified the Android ROM removing some of the officially included algorithms. Nevertheless, it can be checked in the exception instance itself by calling `isDeviceIncompatible`. By doing so you can decide the fallback for storing the credentials, such as using the regular `CredentialsManager`.
+- **DPoP key pair lost** — The DPoP key pair is no longer available in the Android KeyStore. The stored credentials are cleared and re-authentication is required.
+- **DPoP key pair mismatch** — The DPoP key pair exists but is different from the one used when the credentials were saved. The stored credentials are cleared and re-authentication is required.
+- **DPoP not configured** — The stored credentials are DPoP-bound but the `AuthenticationAPIClient` used by the credentials manager was not configured with `useDPoP(context)`. The developer needs to call `AuthenticationAPIClient(auth0).useDPoP(context)` and pass the configured client to the credentials manager.
 
-You can access the `code` property of the `CredentialsManagerException` to understand why the operation with `CredentialsManager` has failed and the `message` property of the `CredentialsManagerException` would give you a description of the exception. 
+You can access the `code` property of the `CredentialsManagerException` to understand why the operation with `CredentialsManager` has failed and the `message` property of the `CredentialsManagerException` would give you a description of the exception.
 
-Starting from version `3.0.0` you can even pass the exception to a `when` expression and handle the exception accordingly in your app's logic as shown in the below code snippet: 
+Starting from version `3.0.0` you can even pass the exception to a `when` expression and handle the exception accordingly in your app's logic as shown in the below code snippet:
 
 ```kotlin
 when(credentialsManagerException) {
-    CredentialsManagerException.NO_CREDENTIALS - > {
+    CredentialsManagerException.NO_CREDENTIALS -> {
         // handle no credentials scenario
     }
 
-    CredentialsManagerException.NO_REFRESH_TOKEN - > {
+    CredentialsManagerException.NO_REFRESH_TOKEN -> {
         // handle no refresh token scenario
     }
 
-    CredentialsManagerException.STORE_FAILED - > {
+    CredentialsManagerException.STORE_FAILED -> {
         // handle store failed scenario
     }
+
+    CredentialsManagerException.DPOP_KEY_MISSING -> {
+        // DPoP key was lost 
+        // Clear local state and prompt user to re-authenticate
+    }
+
+    CredentialsManagerException.DPOP_KEY_MISMATCH -> {
+        // DPoP key exists but doesn't match the one used at login (key rotation)
+        // Clear local state and prompt user to re-authenticate
+    }
+
+    CredentialsManagerException.DPOP_NOT_CONFIGURED -> {
+        // Developer forgot to call useDPoP() on the AuthenticationAPIClient
+        // passed to the credentials manager. Fix the client configuration.
+    }
     // ... similarly for other error codes
 }
 ```