feat: Add automatic retry mechanism for credential renewal

Author: sanchitmehta94

Auth0/Auth0APIError.swift

@@ -106,6 +106,25 @@ extension Auth0APIError {
         ]
     }
 
+    /// Determines if the error is retryable based on its type.
+    ///
+    /// Returns `true` for:
+    /// - Network errors (as determined by ``isNetworkError``)
+    /// - Rate limiting errors (HTTP 429)
+    /// - Server errors (HTTP 5xx)
+    ///
+    /// - Returns: `true` if the error is retryable, `false` otherwise.
+    var isRetryable: Bool {
+        // Retry on network errors
+        if self.isNetworkError {
+            return true
+        }
+
+        // Retry on rate limiting (429) or server errors (5xx)
+        let statusCode = self.statusCode
+        return statusCode == 429 || (500...599).contains(statusCode)
+    }
+
 }
 
 func json(_ data: Data?) -> Any? {

Auth0/CredentialsManager.swift

@@ -35,6 +35,7 @@ public struct CredentialsManager: Sendable {
 
     private let storeKey: String
     private let authentication: Authentication
+    private let maxRetries: Int
     #if WEB_AUTH_PLATFORM
     var bioAuth: BioAuthentication?
     // Biometric session management - using a class to allow mutation in non-mutating methods
@@ -57,12 +58,15 @@ public struct CredentialsManager: Sendable {
     ///   - authentication: Auth0 Authentication API client.
     ///   - storeKey:       Key used to store user credentials in the Keychain. Defaults to 'credentials'.
     ///   - storage:        The ``CredentialsStorage`` instance used to manage credentials storage. Defaults to a standard `SimpleKeychain` instance.
+    ///   - maxRetries:     Maximum number of retry attempts for credential renewal on transient errors. Defaults to 0.
     public init(authentication: Authentication,
                 storeKey: String = "credentials",
-                storage: CredentialsStorage = SimpleKeychain()) {
+                storage: CredentialsStorage = SimpleKeychain(),
+                maxRetries: Int = 0) {
         self.storeKey = storeKey
         self.authentication = authentication
         self.sendableStorage = SendableBox(value: storage)
+        self.maxRetries = max(0, maxRetries)
     }
 
     /// Retrieves the user information from the Keychain synchronously, without checking if the credentials are expired.
@@ -743,6 +747,23 @@ public struct CredentialsManager: Sendable {
                                      headers: [String: String],
                                      forceRenewal: Bool,
                                      callback: @escaping (CredentialsManagerResult<Credentials>) -> Void) {
+        self.retrieveCredentialsWithRetry(scope: scope,
+                                         minTTL: minTTL,
+                                         parameters: parameters,
+                                         headers: headers,
+                                         forceRenewal: forceRenewal,
+                                         retryCount: 0,
+                                         callback: callback)
+    }
+
+    // swiftlint:disable:next function_parameter_count function_body_length
+    private func retrieveCredentialsWithRetry(scope: String?,
+                                             minTTL: Int,
+                                             parameters: [String: Any],
+                                             headers: [String: String],
+                                             forceRenewal: Bool,
+                                             retryCount: Int,
+                                             callback: @escaping (CredentialsManagerResult<Credentials>) -> Void) {
         SynchronizationBarrier.shared.execute { complete in
             guard let credentials = self.retrieveCredentials() else {
                 complete()
@@ -782,13 +803,34 @@ public struct CredentialsManager: Sendable {
                             callback(.success(newCredentials))
                         }
                     case .failure(let error):
-                        complete()
-                        callback(.failure(CredentialsManagerError(code: .renewFailed, cause: error)))
+                        // Check if we should retry based on error type and retry count
+                        if self.shouldRetryRenewal(for: error, retryCount: retryCount) {
+                            complete()
+                            // Calculate exponential backoff delay: 0.5s, 1s, 2s, etc.
+                            let delay = pow(2.0, Double(retryCount)) * 0.5
+                            DispatchQueue.global(qos: .utility).asyncAfter(deadline: .now() + delay) {
+                                self.retrieveCredentialsWithRetry(scope: scope,
+                                                                 minTTL: minTTL,
+                                                                 parameters: parameters,
+                                                                 headers: headers,
+                                                                 forceRenewal: forceRenewal,
+                                                                 retryCount: retryCount + 1,
+                                                                 callback: callback)
+                            }
+                        } else {
+                            complete()
+                            callback(.failure(CredentialsManagerError(code: .renewFailed, cause: error)))
+                        }
                     }
                 }
         }
     }
 
+    private func shouldRetryRenewal(for error: AuthenticationError, retryCount: Int) -> Bool {
+        guard retryCount < self.maxRetries else { return false }
+        return error.isRetryable
+    }
+
     private func retrieveSSOCredentials(parameters: [String: Any],
                                         headers: [String: String],
                                         callback: @escaping (CredentialsManagerResult<SSOCredentials>) -> Void) {

EXAMPLES.md

@@ -484,6 +484,45 @@ credentialsManager
 > [!CAUTION]
 > To ensure that no concurrent renewal requests get made, do not call this method from multiple Credentials Manager instances. The Credentials Manager cannot synchronize requests across instances.
 
+#### Automatic retry on transient errors
+
+The Credentials Manager includes automatic retry logic for credential renewal when transient errors occur. This helps handle scenarios where network requests fail temporarily, such as:
+
+- Network connectivity issues (timeouts, connection lost, DNS failures)
+- Rate limiting responses (HTTP 429)
+- Server errors (HTTP 5xx)
+
+**How it works:**
+
+When a renewal request fails due to a transient error, the Credentials Manager will automatically retry the request with exponential backoff (0.5s, 1s, 2s, 4s, etc.). This addresses the following scenario:
+
+1. Request A calls `credentials()` and starts a token refresh
+2. Request A successfully hits the server and gets new credentials
+3. Request A fails on the way back (network issue), never reaching the client
+4. Later, request B retries with the same (old) refresh token
+
+To fully leverage the retry mechanism, ensure your Auth0 tenant's **Rotation Overlap Period** is set to at least 180 seconds. This overlap window ensures the old refresh token remains valid during retry attempts even if the backend resource was already updated. You can configure this setting in your Auth0 Dashboard under **Applications > [Your Application] > Settings > Refresh Token Rotation**.
+
+**Configure retry behavior:**
+
+By default, retries are disabled. You can enable retries by specifying a maximum retry count when creating the Credentials Manager. It is advisable to set a maximum of 2 retries, which provides sufficient resilience without introducing excessive delays or unnecessary network requests.
+
+```swift
+// Enable up to 2 retry attempts (recommended maximum)
+let credentialsManager = CredentialsManager(
+    authentication: Auth0.authentication(),
+    maxRetries: 2
+)
+```
+
+
+**Important considerations:**
+
+- Retries only occur for transient errors (network issues, rate limiting, server errors)
+- Permanent errors (invalid refresh token, authorization failures) will not be retried
+- Each retry uses exponential backoff to avoid overwhelming the server
+- The 180-second refresh token overlap window ensures retries can succeed even after a successful backend renewal
+
 ### Renew stored credentials
 
 The `credentials()` method automatically renews the stored credentials when needed, using the [refresh token](https://auth0.com/docs/secure/tokens/refresh-tokens). However, you can also force a renewal using the `renew()` method. **This method is thread-safe**.