Refresh Token Interceptor: Ktor | Retrofit | Apollo GraphQL

Key Points

• Research suggests you can implement refresh token interceptors in Kotlin using Ktor, Retrofit, and Apollo GraphQL to handle expired access tokens seamlessly.
• It seems likely that Ktor uses a refreshTokens callback, Retrofit leverages OkHttp’s Authenticator, and Apollo GraphQL uses HttpInterceptors for token refreshing.
• The evidence leans toward each library having unique approaches, with code examples provided for each using the latest versions: Ktor 3.1.0, Retrofit 2.11.0, and Apollo GraphQL 4.1.1 .
• An unexpected detail is that Ktor’s implementation is multiplatform-friendly, while Retrofit is primarily for Android, and Apollo GraphQL supports Kotlin Multiplatform (KMP).

Introduction to Refresh Tokens

Refresh tokens are like a backup plan for your app’s authentication. They let you get new access tokens when the old ones expire, keeping users logged in without needing to log in again. This is super handy for apps that need to stay connected, like social media or banking apps.

Implementing in Ktor

For Ktor, which is great for building clients and servers in Kotlin, you can set up bearer authentication with a refreshTokens callback. This kicks in when the server says “401 Unauthorized,” meaning your access token is no good. Here’s a quick example:

• Set up the HttpClient with bearer authentication and a refresh logic:
• Load initial tokens and define how to refresh them when needed.

import io.ktor.client.*
import io.ktor.client.features.auth.*
import io.ktor.client.features.auth.providers.*
import io.ktor.client.request.*
import io.ktor.http.*

val client = HttpClient {
    install(Auth) {
        bearer {
            loadTokens {
                BearerTokens("accessToken", "refreshToken")
            }
            refreshTokens {
                val response = client.post<RefreshTokenResponse>("https://example.com/refresh") {
                    body = RefreshTokenRequest(oldTokens?.refreshToken ?: "")
                }
                BearerTokens(response.accessToken, response.refreshToken)
            }
        }
    }
}

This code shows how Ktor handles token refreshing automatically, which is pretty neat for keeping things smooth.

Implementing in Retrofit

Retrofit, a favorite for Android HTTP requests, uses OkHttp under the hood. You can set up an Authenticator to handle token refreshes when you get a 401. Here’s how:

• Create a TokenAuthenticator to check for 401 and refresh the token:
• Retry the request with the new token if successful.

class TokenAuthenticator : Authenticator {
    override fun authenticate(route: Route?, response: Response): Request? {
        if (response.code == 401) {
            val newToken = refreshToken()
            if (newToken != null) {
                return response.request.newBuilder()
                    .header("Authorization", "Bearer $newToken")
                    .build()
            }
        }
        return null
    }

    private fun refreshToken(): String? {
        return "newAccessToken"
    }
}

Then, add it to your OkHttpClient when building Retrofit. This way, it handles the refresh behind the scenes, which is great for Android apps.

Implementing in Apollo GraphQL

For Apollo GraphQL, which is awesome for GraphQL queries in Kotlin, you can use an HttpInterceptor to manage tokens. This lets you add headers and handle 401 responses by refreshing the token. Here’s an example:

• Set up an interceptor to add the token and refresh if needed:
• Use mutex for thread safety when updating tokens.

class AuthorizationInterceptor : HttpInterceptor {
    private val mutex = Mutex()
    private var token: String? = null

    override suspend fun intercept(request: HttpRequest, chain: HttpInterceptorChain): HttpResponse {
        token = mutex.withLock { getToken() }
        val response = chain.proceed(request.newBuilder().addHeader("Authorization", "Bearer $token").build())
        return if (response.statusCode == 401) {
            token = mutex.withLock { refreshToken() }
            chain.proceed(request.newBuilder().addHeader("Authorization", "Bearer $token").build())
        } else {
            response
        }
    }
}

Add this to your ApolloClient, and it will handle token refreshes for your GraphQL queries, which is perfect for apps using GraphQL APIs.

---

Detailed Analysis and Insights

Welcome to a comprehensive exploration of implementing refresh token interceptors in Kotlin, focusing on Ktor, Retrofit, and Apollo GraphQL. This analysis aims to provide detailed guidance on setting up these mechanisms using the latest library versions, ensuring compatibility with Kotlin and Android development, and considering Kotlin Multiplatform (KMP) where applicable. The content is informed by official documentation and community resources, aligning with EEAT principles for credibility and engagement.

Introduction and Context

Authentication is a critical aspect of modern mobile and web applications, particularly when dealing with APIs that require token-based security. Access tokens, typically short-lived for security, expire after a set period, necessitating the use of refresh tokens to obtain new access tokens without user intervention. This note explores how to implement refresh token interceptors in three popular Kotlin libraries: Ktor, Retrofit, and Apollo GraphQL, using their latest versions as identified through recent documentation and repository searches.

The latest versions, based on current research, are Ktor 3.1.0 (Ktor 3.1.0 Release | The Kotlin Blog), Retrofit 2.11.0 (GitHub – square/retrofit: A type-safe HTTP client for Android and the JVM), and Apollo GraphQL 4.1.1 (Gradle – Plugin: com.apollographql.apollo). These versions ensure compatibility with Kotlin 2.0 and later, as well as Android API levels supported by each library.

Understanding Refresh Tokens and Interceptors

Refresh tokens are long-lived credentials used to obtain new access tokens when the current access token expires, typically triggered by a 401 Unauthorized HTTP response. Interceptors, in the context of networking libraries, are mechanisms to intercept and modify requests or responses, ideal for adding authentication headers or handling token refreshes. Each library provides distinct approaches, which we’ll explore in detail.

Implementing Refresh Tokens in Ktor

Ktor, developed by JetBrains, is a multiplatform framework for building asynchronous servers and clients. For client-side operations, Ktor offers the Auth feature with bearer authentication, including a refreshTokens callback for handling token refreshes. This is particularly useful in KMP projects, as Ktor supports multiple platforms.

The implementation involves setting up the HttpClient with the Auth feature, as shown in the example:

import io.ktor.client.*
import io.ktor.client.features.auth.*
import io.ktor.client.features.auth.providers.*
import io.ktor.client.request.*
import io.ktor.http.*

val client = HttpClient {
    install(Auth) {
        bearer {
            loadTokens {
                BearerTokens("accessToken", "refreshToken")
            }
            refreshTokens {
                val response = client.post<RefreshTokenResponse>("https://example.com/refresh") {
                    body = RefreshTokenRequest(oldTokens?.refreshToken ?: "")
                }
                BearerTokens(response.accessToken, response.refreshToken)
            }
        }
    }
}

This code, adapted from Bearer authentication in Ktor Client | Ktor Documentation, shows how to load initial tokens and define the refresh logic. The refreshTokens callback is automatically invoked on 401 responses, making it seamless for multiplatform use. An unexpected detail is that Ktor’s implementation is inherently multiplatform, allowing shared code across Android, iOS, and JVM, which is not as straightforward with Retrofit.

Refresh Tokens with Retrofit

Retrofit, developed by Square, is a type-safe HTTP client primarily for Android, leveraging OkHttp for network operations. For refresh token handling, you can use OkHttp’s Authenticator interface, which is designed to handle authentication challenges like 401 responses. This approach is well-documented in community tutorials, such as Android: Refreshing token proactively with OkHttp Interceptors | by Joan Barroso Garrido | Tiendeo Tech | Medium.

Here’s an example implementation:

class TokenAuthenticator : Authenticator {
    override fun authenticate(route: Route?, response: Response): Request? {
        if (response.code == 401) {
            val newToken = refreshToken()
            if (newToken != null) {
                return response.request.newBuilder()
                    .header("Authorization", "Bearer $newToken")
                    .build()
            }
        }
        return null
    }

    private fun refreshToken(): String? {
        return "newAccessToken"
    }
}

Then, integrate it into your Retrofit setup:

val okHttpClient = OkHttpClient.Builder()
    .authenticator(TokenAuthenticator())
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://example.com/")
    .client(okHttpClient)
    .addConverterFactory(GsonConverterFactory.create())
    .build()

This approach is Android-centric, with limited direct support for KMP, though you can use it in shared code with platform-specific implementations. The evidence leans toward Retrofit being robust for Android, but it requires additional setup for multiplatform scenarios compared to Ktor.

Handling Refresh Tokens in Apollo GraphQL

Apollo GraphQL for Kotlin, developed by Apollo, is a strongly-typed GraphQL client supporting KMP, making it ideal for cross-platform development. For authentication, it provides an HttpInterceptor interface, allowing custom logic for adding headers and handling responses, including token refreshes. This is detailed in Authenticate your operations – Apollo GraphQL Docs.

Here’s an example:

class AuthorizationInterceptor : HttpInterceptor {
    private val mutex = Mutex()
    private var token: String? = null

    override suspend fun intercept(request: HttpRequest, chain: HttpInterceptorChain): HttpResponse {
        token = mutex.withLock { getToken() }
        val response = chain.proceed(request.newBuilder().addHeader("Authorization", "Bearer $token").build())
        return if (response.statusCode == 401) {
            token = mutex.withLock { refreshToken() }
            chain.proceed(request.newBuilder().addHeader("Authorization", "Bearer $token").build())
        } else {
            response
        }
    }
}

Set up your ApolloClient with this interceptor:

val apolloClient = ApolloClient.Builder()
    .serverUrl("https://example.com/graphql")
    .httpInterceptors(listOf(AuthorizationInterceptor()))
    .build()

This implementation is multiplatform, leveraging Kotlin coroutines for asynchronous operations, and is particularly suited for GraphQL APIs. An unexpected detail is that Apollo’s HttpInterceptor is similar to OkHttp’s, but it’s designed for KMP, offering broader platform support than Retrofit’s approach.

Comparison and Best Practices

To facilitate comparison, here’s a table summarizing the approaches:

Library	Approach	Key Feature	Multiplatform Support
Ktor	refreshTokens callback in bearer	Automatic token refresh on 401	Yes, KMP-ready
Retrofit	OkHttp Authenticator	Handles authentication challenges	Limited, Android-focused
Apollo GraphQL	HttpInterceptor	Custom logic for token refresh	Yes, KMP-supported

Each library has unique strengths: Ktor for its multiplatform ease, Retrofit for Android robustness, and Apollo for GraphQL-specific needs. Best practices include ensuring thread safety with mutexes, handling refresh token expiration by logging out or prompting re-authentication, optimizing performance by avoiding concurrent refreshes, and securing token storage using Android’s Keystore or encrypted storage.

Conclusion and Personal Take

This detailed exploration shows how to implement refresh token interceptors in Ktor, Retrofit, and Apollo GraphQL using Kotlin, with considerations for KMP where applicable. Each library offers distinct mechanisms, with Ktor and Apollo being more multiplatform-friendly, while Retrofit excels in Android contexts. Personally, I find Ktor’s built-in refreshTokens callback the most seamless, especially for KMP projects, but Retrofit’s Authenticator is a solid choice for Android apps. What do you think? Share your thoughts in the comments, and let’s discuss!

Key Citations:

• Ktor 3.1.0 Release | The Kotlin Blog
• GitHub – square/retrofit: A type-safe HTTP client for Android and the JVM
• Gradle – Plugin: com.apollographql.apollo
• Bearer authentication in Ktor Client | Ktor Documentation
• Android: Refreshing token proactively with OkHttp Interceptors | by Joan Barroso Garrido | Tiendeo Tech | Medium
• Authenticate your operations – Apollo GraphQL Docs