As Android engineers, we’re constantly building apps that need to securely authenticate users and interact with backend APIs. One of the most critical parts of this puzzle is token management — making sure authentication is safe, seamless, and user-friendly.
What is a Token?
A token is a digital key that grants access to protected resources (like APIs). Instead of repeatedly sending usernames and passwords (insecure and inefficient), the client app uses tokens to prove identity and permissions.
Tokens usually come in two flavors:
-
Access Token – short-lived, used for every API request.
-
Refresh Token – longer-lived, used to obtain a new access token once it expires.
Think of an access token as a hotel room key card and the refresh token as your hotel booking record. If your key card stops working, the receptionist (auth server) issues a new one, as long as your booking is valid.
Token Lifecycle in Android
Here’s the typical flow:
-
Login – User authenticates with email/password/biometric → server issues access + refresh token.
-
Store Securely – Tokens are stored securely on-device.
-
Use in Requests – Access token is attached to each API call.
-
Refresh When Expired – On
401 Unauthorized, refresh token is used to fetch a new access token. -
Logout – Tokens are cleared.
Visual Flow:
Best Practices for Token Management
-
Use Access + Refresh Token Strategy
-
Access tokens: short-lived.
-
Refresh tokens: long-lived but securely stored.
-
-
Secure Storage
-
Use EncryptedSharedPreferences / Encrypted DataStore.
-
Use Android Keystore for refresh tokens (hardware-backed security).
-
Keep access token in memory only to reduce exposure.
-
-
Automatic Token Handling
-
Use OkHttp Interceptor to attach tokens.
-
Use OkHttp Authenticator to refresh tokens when expired.
-
Never manually add tokens in API calls.
-
-
Follow Clean Architecture
-
Keep token logic in Data layer.
-
Expose login/refresh/logout via Use Cases (Domain layer).
-
UI observes AuthState from ViewModel.
-
-
Security Best Practices
-
Always use HTTPS (TLS).
-
Never log tokens.
-
Force logout if refresh fails.
-
Test token expiration scenarios.
-
Example Implementation in Android
Retrofit API
interface AuthApi {
@POST("auth/login")
suspend fun login(@Body request: LoginRequest): TokenResponse
@POST("auth/refresh")
suspend fun refreshToken(@Body request: RefreshRequest): TokenResponse
}
Token Storage
class TokenStorage(private val context: Context) {
private val Context.dataStore by preferencesDataStore("secure_prefs")
private val ACCESS_TOKEN = stringPreferencesKey("access_token")
private val REFRESH_TOKEN = stringPreferencesKey("refresh_token")
suspend fun saveTokens(access: String, refresh: String) {
context.dataStore.edit {
it[ACCESS_TOKEN] = access
it[REFRESH_TOKEN] = refresh
}
}
suspend fun getAccessToken() = context.dataStore.data.first()[ACCESS_TOKEN]
suspend fun getRefreshToken() = context.dataStore.data.first()[REFRESH_TOKEN]
suspend fun clearTokens() = context.dataStore.edit { it.clear() }
}
OkHttp Interceptor
class AuthInterceptor(private val tokenProvider: TokenProvider) : Interceptor {
override fun intercept(chain: Interceptor.Chain): Response {
val token = tokenProvider.getAccessToken()
val newRequest = chain.request().newBuilder()
.addHeader("Authorization", "Bearer $token")
.build()
return chain.proceed(newRequest)
}
}
OkHttp Authenticator (Auto Refresh)
class TokenAuthenticator(private val repo: AuthRepository) : Authenticator {
override fun authenticate(route: Route?, response: Response): Request? {
return runBlocking {
if (repo.refreshToken()) {
repo.getAccessToken()?.let { newToken ->
response.request.newBuilder()
.header("Authorization", "Bearer $newToken")
.build()
}
} else null
}
}
}
Key Takeaways
-
Access tokens should be short-lived → reduces risk.
-
Refresh tokens should be secured in Keystore → prevents theft.
-
Automatic handling via Interceptor + Authenticator → reduces bugs.
-
Clean architecture separation → makes token logic testable + maintainable.
By following these best practices, you’ll deliver apps that are secure, reliable, and seamless for users.
Common Mistakes to Avoid
Even experienced developers sometimes fall into these pitfalls:
-
Storing tokens in plain
SharedPreferences-
❌ Vulnerable to root access and backup extraction.
-
✅ Use Encrypted DataStore or Keystore.
-
-
Using long-lived access tokens
-
❌ If stolen, attackers can access APIs indefinitely.
-
✅ Keep access tokens short-lived, rely on refresh tokens.
-
-
Not handling
401 Unauthorizedproperly-
❌ App just crashes or shows an error.
-
✅ Automatically refresh the token using
Authenticator.
-
-
Storing refresh tokens in memory only
-
❌ Refresh token will be lost when the app restarts, forcing re-login.
-
✅ Store refresh token securely on disk (Keystore-backed).
-
-
Logging tokens in Crashlytics or Logcat
-
❌ Attackers can retrieve sensitive tokens from logs.
-
✅ Never log tokens, redact them if necessary.
-
-
Not clearing tokens on logout
-
❌ User data can remain exposed.
-
✅ Always clear tokens from secure storage on logout.
-
-
Refreshing tokens too eagerly
-
❌ Wastes server resources and battery.
-
✅ Refresh only when expired (lazy refresh).
Token Lifecycle Management
-
On login → store both access + refresh token securely.
-
On every request → add access token.
-
On
401→ refresh token automatically. -
On app start → check if refresh token exists & is valid.
-
On logout → clear all tokens from storage.
Final Words
Token management might sound like a low-level detail, but in reality, it’s the backbone of secure Android apps. Whether you’re building fintech, healthcare, or large-scale consumer apps, these practices ensure your app is both safe and user-friendly.
📢 Feedback: Did you find this article helpful? Let me know your thoughts or suggestions for improvements! Please leave a comment below. I’d love to hear from you! 👇
Happy coding! 💻
Posts
