Updated the examples.md file

Author: pmathew92

EXAMPLES.md

@@ -11,6 +11,7 @@
   - [Changing the Return To URL scheme](#changing-the-return-to-url-scheme)
   - [Specify a Custom Logout URL](#specify-a-custom-logout-url)
   - [Trusted Web Activity](#trusted-web-activity)
+  - [DPoP [EA]](#dpop-ea)
   - [Authentication API](#authentication-api)
     - [Login with database connection](#login-with-database-connection)
     - [Login using MFA with One Time Password code](#login-using-mfa-with-one-time-password-code)
@@ -21,6 +22,7 @@
     - [Get user information](#get-user-information)
     - [Custom Token Exchange](#custom-token-exchange)
     - [Native to Web SSO login [EA]](#native-to-web-sso-login-ea)
+    - [DPoP [EA]](#dpop-ea-1)
   - [My Account API](#my-account-api)
     - [Enroll a new passkey](#enroll-a-new-passkey)
   - [Credentials Manager](#credentials-manager)
@@ -208,6 +210,76 @@ WebAuthProvider.login(account)
     .await(this)
 ```
 
+## DPoP [EA]
+
+> [!NOTE]  
+> This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access). Please reach out to Auth0 support to get it enabled for your tenant.
+
+[DPoP](https://www.rfc-editor.org/rfc/rfc9449.html) (Demonstrating Proof of Posession) is an application-level mechanism for sender-constraining OAuth 2.0 access and refresh tokens by proving that the app is in possession of a certain private key. You can enable it by calling the `useDPoP(context:Context)` method.
+
+```kotlin
+WebAuthProvider
+    .useDPoP(requireContext())
+    .login(account)
+    .start(requireContext(), object : Callback<Credentials, AuthenticationException> {
+        override fun onSuccess(result: Credentials) {
+           println("Credentials $result")
+        }
+        override fun onFailure(error: AuthenticationException) {
+            print("Error $error")
+        }
+    })
+```
+
+> [!IMPORTANT]
+> DPoP will only be used for new user sessions created after enabling it. DPoP **will not** be applied to any requests involving existing access and refresh tokens (such as exchanging the refresh token for new credentials).
+>
+> This means that, after you've enabled it in your app, DPoP will only take effect when users log in again. It's up to you to decide how to roll out this change to your users. For example, you might require users to log in again the next time they open your app. You'll need to implement the logic to handle this transition based on your app's requirements.
+
+When making requests to your own APIs, use the `DPoP.getHeaderData()` method to get the `Authorization` and `DPoP` header values to be used. The `Authorization` header value is generated using the access token and token type, while the `DPoP` header value is the generated DPoP proof.
+
+```kotlin
+val url ="https://example.com/api/endpoint"
+val httpMethod = "GET"
+ val headerData = DPoPProvider.getHeaderData(
+                    httpMethod, url,
+                    accessToken, tokenType
+                )
+httpRequest.apply{
+    addHeader("Authorization", headerData.authorizationHeader)
+    headerData.dpopProof?.let {
+        addHeader("DPoP", it)
+    }
+}
+```
+If your API is issuing DPoP nonce's to prevent replay attacks, you can pass the nonce value to the `getHeaderData()` method to include it in the DPoP proof. Use the `DPoPProvider.isNonceRequiredError(response: Response)` method to check if a particular API response failed because a nonce is required.
+
+```kotlin
+if (DPoPProvider.isNonceRequiredError(response)) {
+    val nonce = response.headers["DPoP-Nonce"]
+    val dpopProof = DPoPProvider.generateProof(
+        url, httpMethod, accessToken, nonce
+    )
+    // Retry the request with the new proof
+}
+```
+
+On logout, you should call `DPoPProvider.clearKeyPair()` to delete the user's key pair from the Keychain.
+
+```kotlin
+WebAuthProvider.logout(account)
+            .start(requireContext(), object : Callback<Void?, AuthenticationException> {
+                override fun onSuccess(result: Void?) {
+                    DPoPProvider.clearKeyPair()
+                }
+                override fun onFailure(error: AuthenticationException) {
+                }
+
+            })
+```
+> [!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
 
 The client provides methods to authenticate the user against the Auth0 server.
@@ -651,6 +723,62 @@ authentication
 ```
 </details>
 
+## DPoP [EA]
+
+> [!NOTE]  
+> This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access). Please reach out to Auth0 support to get it enabled for your tenant.
+
+[DPoP](https://www.rfc-editor.org/rfc/rfc9449.html) (Demonstrating Proof of Posession) is an application-level mechanism for sender-constraining OAuth 2.0 access and refresh tokens by proving that the app is in possession of a certain private key. You can enable it by calling the `useDPoP(context: Context)` method. This ensures that DPoP proofs are generated for requests made through the AuthenticationAPI client.
+
+```kotlin
+val client = AuthenticationAPIClient(account).useDPoP(context)
+```
+
+[!IMPORTANT]
+> DPoP will only be used for new user sessions created after enabling it. DPoP **will not** be applied to any requests involving existing access and refresh tokens (such as exchanging the refresh token for new credentials).
+>
+> This means that, after you've enabled it in your app, DPoP will only take effect when users log in again. It's up to you to decide how to roll out this change to your users. For example, you might require users to log in again the next time they open your app. You'll need to implement the logic to handle this transition based on your app's requirements.
+
+When making requests to your own APIs, use the `DPoP.getHeaderData()` method to get the `Authorization` and `DPoP` header values to be used. The `Authorization` header value is generated using the access token and token type, while the `DPoP` header value is the generated DPoP proof.
+
+```kotlin
+val url ="https://example.com/api/endpoint"
+val httpMethod = "GET"
+ val headerData = DPoPProvider.getHeaderData(
+                    httpMethod, url,
+                    accessToken, tokenType
+                )
+httpRequest.apply{
+    addHeader("Authorization", headerData.authorizationHeader)
+    headerData.dpopProof?.let {
+        addHeader("DPoP", it)
+    }
+}
+```
+If your API is issuing DPoP nonce's to prevent replay attacks, you can pass the nonce value to the `getHeaderData()` method to include it in the DPoP proof. Use the `DPoPProvider.isNonceRequiredError(response: Response)` method to check if a particular API response failed because a nonce is required.
+
+```kotlin
+if (DPoPProvider.isNonceRequiredError(response)) {
+    val nonce = response.headers["DPoP-Nonce"]
+    val dpopProof = DPoPProvider.generateProof(
+        url, httpMethod, accessToken, nonce
+    )
+    // Retry the request with the new proof
+}
+```
+
+On logout, you should call `DPoPProvider.clearKeyPair()` to delete the user's key pair from the Keychain.
+
+```kotlin
+
+DPoPProvider.clearKeyPair()
+
+```
+
+> [!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.
+
+
 
 ## My Account API
 

auth0/src/main/java/com/auth0/android/authentication/AuthenticationAPIClient.kt

@@ -71,7 +71,7 @@ public class AuthenticationAPIClient @VisibleForTesting(otherwise = VisibleForTe
      * Enable DPoP for this client.
      */
     @RequiresApi(Build.VERSION_CODES.M)
-    public override fun enableDPoP(context: Context): AuthenticationAPIClient {
+    public override fun useDPoP(context: Context): AuthenticationAPIClient {
         DPoPProvider.generateKeyPair(context)
         return this
     }

auth0/src/main/java/com/auth0/android/dpop/SenderConstraining.kt

@@ -10,6 +10,6 @@ public interface SenderConstraining<T> {
     /**
      * Enables DPoP for authentication requests.
      */
-    public fun enableDPoP(context: Context): T
+    public fun useDPoP(context: Context): T
 
 }

auth0/src/main/java/com/auth0/android/provider/WebAuthProvider.kt

@@ -51,7 +51,7 @@ public object WebAuthProvider : SenderConstraining<WebAuthProvider> {
     }
 
     @RequiresApi(Build.VERSION_CODES.M)
-    public override fun enableDPoP(context: Context): WebAuthProvider {
+    public override fun useDPoP(context: Context): WebAuthProvider {
         DPoPProvider.generateKeyPair(context)
         return this
     }

auth0/src/test/java/com/auth0/android/provider/WebAuthProviderTest.kt

@@ -325,7 +325,7 @@ public class WebAuthProviderTest {
     public fun enablingDPoPWillGenerateNEwKEyPairIfOneDoesNotExist() {
         `when`(mockKeyStore.hasKeyPair()).thenReturn(false)
         val context: Context = mock()
-        WebAuthProvider.enableDPoP(context)
+        WebAuthProvider.useDPoP(context)
         login(account)
             .start(activity, callback)
         verify(mockKeyStore).generateKeyPair(context)
@@ -352,7 +352,7 @@ public class WebAuthProviderTest {
         `when`(mockKeyStore.hasKeyPair()).thenReturn(true)
         `when`(mockKeyStore.getKeyPair()).thenReturn(Pair(mock(), FakeECPublicKey()))
 
-        WebAuthProvider.enableDPoP(mock())
+        WebAuthProvider.useDPoP(mock())
         login(account)
             .start(activity, callback)
         verify(activity).startActivity(intentCaptor.capture())