auth0 · pmathew92 · May 8, 2025 · Mar 11, 2025 · Mar 17, 2025 · Mar 18, 2025
@@ -731,7 +731,9 @@ public class AuthenticationAPIClient @VisibleForTesting(otherwise = VisibleForTe
     }
 
     /**
-     * Requests new Credentials using a valid Refresh Token. The received token will have the same audience and scope as first requested.
+     * Requests new Credentials using a valid Refresh Token. You can request credentials for a specific API by passing its audience value. The default scopes
+     * configured for the API will be granted if you don't request any specific scopes.
+     *
      *
      * This method will use the /oauth/token endpoint with the 'refresh_token' grant, and the response will include an id_token and an access_token if 'openid' scope was requested when the refresh_token was obtained.
      * Additionally, if the application has Refresh Token Rotation configured, a new one-time use refresh token will also be included in the response.
@@ -740,22 +742,35 @@ public class AuthenticationAPIClient @VisibleForTesting(otherwise = VisibleForTe
      *
      * Example usage:
      * ```
-     * client.renewAuth("{refresh_token}")
-     *     .addParameter("scope", "openid profile email")
+     * client.renewAuth("{refresh_token}","{audience}","{scope})
      *     .start(object: Callback<Credentials, AuthenticationException> {
      *         override fun onSuccess(result: Credentials) { }
      *         override fun onFailure(error: AuthenticationException) { }
      * })
      * ```
      *
      * @param refreshToken used to fetch the new Credentials.
+     * @param audience Identifier of the API that your application is requesting access to. Defaults to null.
+     * @param scope Space-separated list of scope values to request. Defaults to null.
      * @return a request to start
      */
-    public fun renewAuth(refreshToken: String): Request<Credentials, AuthenticationException> {
+    public fun renewAuth(
+        refreshToken: String,
+        audience: String? = null,
+        scope: String? = null
+    ): Request<Credentials, AuthenticationException> {
         val parameters = ParameterBuilder.newBuilder()
             .setClientId(clientId)
             .setRefreshToken(refreshToken)
             .setGrantType(ParameterBuilder.GRANT_TYPE_REFRESH_TOKEN)
+            .apply {
+                audience?.let {
+                    setAudience(it)
+                }
+                scope?.let {
+                    setScope(it)
+                }
+            }
             .asDictionary()
         val url = auth0.getDomainUrl().toHttpUrl().newBuilder()
             .addPathSegment(OAUTH_PATH)

@@ -3,6 +3,7 @@ package com.auth0.android.authentication.storage
 import androidx.annotation.VisibleForTesting
 import com.auth0.android.authentication.AuthenticationAPIClient
 import com.auth0.android.callback.Callback
+import com.auth0.android.result.APICredentials
 import com.auth0.android.result.Credentials
 import com.auth0.android.result.SSOCredentials
 import com.auth0.android.util.Clock
@@ -30,6 +31,7 @@ public abstract class BaseCredentialsManager internal constructor(
 
     @Throws(CredentialsManagerException::class)
     public abstract fun saveCredentials(credentials: Credentials)
+    public abstract fun saveApiCredentials(apiCredentials: APICredentials, audience: String)
     public abstract fun getCredentials(callback: Callback<Credentials, CredentialsManagerException>)
     public abstract fun getSsoCredentials(
         parameters: Map<String, String>,
@@ -70,6 +72,15 @@ public abstract class BaseCredentialsManager internal constructor(
         callback: Callback<Credentials, CredentialsManagerException>
     )
 
+    public abstract fun getApiCredentials(
+        audience: String,
+        scope: String? = null,
+        minTtl: Int = 0,
+        parameters: Map<String, String> = emptyMap(),
+        headers: Map<String, String> = emptyMap(),
+        callback: Callback<APICredentials, CredentialsManagerException>
+    )
+
     @JvmSynthetic
     @Throws(CredentialsManagerException::class)
     public abstract suspend fun awaitSsoCredentials(parameters: Map<String, String>)
@@ -115,7 +126,18 @@ public abstract class BaseCredentialsManager internal constructor(
         forceRefresh: Boolean
     ): Credentials
 
+    @JvmSynthetic
+    @Throws(CredentialsManagerException::class)
+    public abstract suspend fun awaitApiCredentials(
+        audience: String,
+        scope: String? = null,
+        minTtl: Int = 0,
+        parameters: Map<String, String> = emptyMap(),
+        headers: Map<String, String> = emptyMap()
+    ): APICredentials
+
     public abstract fun clearCredentials()
+    public abstract fun clearApiCredentials(audience: String)
     public abstract fun hasValidCredentials(): Boolean
     public abstract fun hasValidCredentials(minTtl: Long): Boolean
 

@@ -6,8 +6,12 @@
 import com.auth0.android.authentication.AuthenticationAPIClient
 import com.auth0.android.authentication.AuthenticationException
 import com.auth0.android.callback.Callback
+import com.auth0.android.request.internal.GsonProvider
+import com.auth0.android.result.APICredentials
 import com.auth0.android.result.Credentials
 import com.auth0.android.result.SSOCredentials
+import com.auth0.android.result.toAPICredentials
+import com.google.gson.Gson
 import kotlinx.coroutines.suspendCancellableCoroutine
 import java.util.*
 import java.util.concurrent.Executor
@@ -24,6 +28,9 @@
     jwtDecoder: JWTDecoder,
     private val serialExecutor: Executor
 ) : BaseCredentialsManager(authenticationClient, storage, jwtDecoder) {
+
+    private val gson: Gson = GsonProvider.gson
+
     /**
      * Creates a new instance of the manager that will store the credentials in the given Storage.
      *
@@ -55,6 +62,17 @@
         storage.store(LEGACY_KEY_CACHE_EXPIRES_AT, credentials.expiresAt.time)
     }
 
+    /**
+     * Stores the given [APICredentials] in the storage for the given audience.
+     * @param apiCredentials the API Credentials to be stored
+     * @param audience the audience for which the credentials are stored
+     */
+    override fun saveApiCredentials(apiCredentials: APICredentials, audience: String) {
+        gson.toJson(apiCredentials).let {
+            storage.store(audience, it)
+        }
+    }
+
     /**
      * Creates a new request to exchange a refresh token for a session transfer token that can be used to perform web single sign-on.
      *
@@ -305,6 +323,44 @@
         }
     }
 
+    /**
+     * Retrieves API credentials from storage and automatically renews them using the refresh token if the access
+     * token is expired. Otherwise, the retrieved API credentials will be returned as they are still valid.
+     *
+     * If there are no stored API credentials, the refresh token will be exchanged for a new set of API credentials.
+     * New or renewed API credentials will be automatically persisted in storage.
+     *
+     * @param audience Identifier of the API that your application is requesting access to.
+     * @param scope    the scope to request for the access token. If null is passed, the previous scope will be kept.
+     * @param minTtl   the minimum time in seconds that the access token should last before expiration.
+     * @param parameters additional parameters to send in the request to refresh expired credentials.
+     * @param headers additional headers to send in the request to refresh expired credentials.
+     */
+    @JvmSynthetic
+    @Throws(CredentialsManagerException::class)
+    override suspend fun awaitApiCredentials(
+        audience: String,
+        scope: String?,
+        minTtl: Int,
+        parameters: Map<String, String>,
+        headers: Map<String, String>
+    ): APICredentials {
+        return suspendCancellableCoroutine { continuation ->
+            getApiCredentials(
+                audience, scope, minTtl, parameters, headers,
+                object : Callback<APICredentials, CredentialsManagerException> {
+                    override fun onSuccess(result: APICredentials) {
+                        continuation.resume(result)
+                    }
+
+                    override fun onFailure(error: CredentialsManagerException) {
+                        continuation.resumeWithException(error)
+                    }
+                }
+            )
+        }
+    }
+
     /**
      * Retrieves the credentials from the storage and refresh them if they have already expired.
      * It will fail with [CredentialsManagerException] if the saved access_token or id_token is null,
@@ -496,6 +552,99 @@
         }
     }
 
+
+    /**
+     *  Retrieves API credentials from storage and automatically renews them using the refresh token if the access
+     *  token is expired. Otherwise, the retrieved API credentials will be returned via the success callback as they are still valid.
+     *
+     * If there are no stored API credentials, the refresh token will be exchanged for a new set of API credentials.
+     * New or renewed API credentials will be automatically persisted in storage.
+     *
+     * @param audience Identifier of the API that your application is requesting access to.
+     * @param scope the scope to request for the access token. If null is passed, the previous scope will be kept.
+     * @param minTtl the minimum time in seconds that the access token should last before expiration.
+     * @param parameters additional parameters to send in the request to refresh expired credentials.
+     * @param headers headers to use when exchanging a refresh token for API credentials.
+     * @param callback the callback that will receive a valid [Credentials] or the [CredentialsManagerException].
+     */
+    override fun getApiCredentials(
+        audience: String,
+        scope: String?,
+        minTtl: Int,
+        parameters: Map<String, String>,
+        headers: Map<String, String>,
+        callback: Callback<APICredentials, CredentialsManagerException>
+    ) {
+        serialExecutor.execute {
+            //Check if existing api credentials are present and valid
+            val apiCredentialsJson = storage.retrieveString(audience)
+            apiCredentialsJson?.let {
+                val apiCredentials = gson.fromJson(it, APICredentials::class.java)
+                val willTokenExpire = willExpire(apiCredentials.expiresAt.time, minTtl.toLong())
+                val scopeChanged = hasScopeChanged(apiCredentials.scope, scope)
+                val hasExpired = hasExpired(apiCredentials.expiresAt.time)
+                if (!hasExpired && !willTokenExpire && !scopeChanged) {
+                    callback.onSuccess(apiCredentials)
+                    return@execute
+                }
+            }
+            //Check if refresh token exists or not
+            val refreshToken = storage.retrieveString(KEY_REFRESH_TOKEN)
+            if (refreshToken == null) {
+                callback.onFailure(CredentialsManagerException.NO_REFRESH_TOKEN)
+                return@execute
+            }
+
+            val request = authenticationClient.renewAuth(refreshToken, audience, scope)
+            request.addParameters(parameters)
+
+            for (header in headers) {
+                request.addHeader(header.key, header.value)
+            }
+
+            try {
+                val newCredentials = request.execute()
+                val expiresAt = newCredentials.expiresAt.time
+                val willAccessTokenExpire = willExpire(expiresAt, minTtl.toLong())
+                if (willAccessTokenExpire) {
+                    val tokenLifetime = (expiresAt - currentTimeInMillis - minTtl * 1000) / -1000
@@ -609,3 +609,3 @@
                if (willAccessTokenExpire) {
-                    val tokenLifetime = (expiresAt - currentTimeInMillis - minTtl * 1000) / -1000
+                    val tokenLifetime = (expiresAt - currentTimeInMillis - minTtl.toLong() * 1000) / -1000
                    val wrongTtlException = CredentialsManagerException(
@@ -609,3 +609,3 @@
                if (willAccessTokenExpire) {
-                    val tokenLifetime = (expiresAt - currentTimeInMillis - minTtl * 1000) / -1000
+                    val tokenLifetime = (expiresAt - currentTimeInMillis - minTtl.toLong() * 1000) / -1000
                    val wrongTtlException = CredentialsManagerException(
+                    val wrongTtlException = CredentialsManagerException(
+                        CredentialsManagerException.Code.LARGE_MIN_TTL, String.format(
+                            Locale.getDefault(),
+                            "The lifetime of the renewed Access Token (%d) is less than the minTTL requested (%d). Increase the 'Token Expiration' setting of your Auth0 API in the dashboard, or request a lower minTTL.",
+                            tokenLifetime,
+                            minTtl
+                        )
+                    )
+                    callback.onFailure(wrongTtlException)
+                    return@execute
+                }
+
+                // non-empty refresh token for refresh token rotation scenarios
+                val updatedRefreshToken =
+                    if (TextUtils.isEmpty(newCredentials.refreshToken)) refreshToken else newCredentials.refreshToken
+                val newApiCredentials = newCredentials.toAPICredentials()
+                storage.store(KEY_REFRESH_TOKEN, updatedRefreshToken)
+                storage.store(KEY_ID_TOKEN, newCredentials.idToken)
+                saveApiCredentials(newApiCredentials, audience)
+                callback.onSuccess(newApiCredentials)
+            } catch (error: AuthenticationException) {
+                val exception = when {
+                    error.isRefreshTokenDeleted || error.isInvalidRefreshToken -> CredentialsManagerException.Code.RENEW_FAILED
+
+                    error.isNetworkError -> CredentialsManagerException.Code.NO_NETWORK
+                    else -> CredentialsManagerException.Code.API_ERROR
+                }
+                callback.onFailure(
+                    CredentialsManagerException(
+                        exception, error
+                    )
+                )
+            }
+        }
+
+    }
+
     /**
      * Checks if a non-expired pair of credentials can be obtained from this manager.
      *
@@ -536,6 +685,14 @@
         storage.remove(LEGACY_KEY_CACHE_EXPIRES_AT)
     }
 
+    /**
+     * Removes the credentials for the given audience from the storage if present.
+     */
+    override fun clearApiCredentials(audience: String) {
+        storage.remove(audience)
+        Log.d(TAG, "API Credentials for $audience were just removed from the storage")
+    }
+
     /**
      * Helper method to store the given [SSOCredentials] refresh token in the storage.
      * Method will silently return if the passed credentials have no refresh token.