Authentication is one of the most important parts of a modern mobile application.
Whether you are building an e-commerce app, booking platform, social media application, education platform, banking application, or business management system, users often need to log in before accessing protected features.
With Kotlin Multiplatform (KMP), you can share a large part of your authentication and API logic between Android and iOS.
Combined with Ktor Client, Kotlin Serialization, and a token-based authentication system such as JWT, you can build a reusable authentication architecture that works across multiple platforms.
In this complete guide, you’ll learn:
- What authentication means in KMP
- How login works
- What JWT is
- Access tokens and refresh tokens
- How Ktor handles authentication
- How to create a login API
- How to store tokens
- How to refresh expired tokens
- How to protect API requests
- How to handle logout
- How to organize authentication in
commonMain - Android and iOS platform-specific considerations
- Security best practices
- A complete KMP authentication architecture
What Is Authentication?
Authentication is the process of verifying the identity of a user.
For example, when a user enters:
Email: john@example.com
Password: ********
the application sends the credentials to the backend.
The server verifies the credentials.
If they are valid, the server returns authentication information, commonly an access token and sometimes a refresh token.
The flow looks like:
User
↓
Login Screen
↓
Email + Password
↓
KMP Shared Code
↓
Ktor Client
↓
Backend API
↓
Validate Credentials
↓
Access Token / Refresh Token
↓
Store Securely
↓
Authenticated Requests
Authentication vs Authorization
These two concepts are often confused.
Authentication
Authentication answers:
Who are you?
Example:
User → john@example.com
Authorization
Authorization answers:
What are you allowed to do?
For example:
Admin → Can delete users
User → Cannot delete users
A typical application uses both.
Authentication
↓
Identify User
↓
Authorization
↓
Check Permissions
What Is Kotlin Multiplatform Authentication?
Kotlin Multiplatform allows you to share authentication-related logic across platforms.
Instead of implementing the same login flow separately:
Android Login Logic
iOS Login Logic
you can share:
Login API
Request Models
Response Models
Token Handling
Authentication State
Repository
Business Logic
A simplified architecture is:
Shared KMP Code
|
+---------+---------+
| |
Android iOS
| |
UI Layer UI Layer
\ /
\ /
Shared Auth Logic
|
Ktor Client
|
Backend API
What Is JWT?
JWT stands for JSON Web Token.
It is a compact token format commonly used for transmitting claims between systems.
A JWT commonly looks like:
xxxxx.yyyyy.zzzzz
It consists of three Base64URL-encoded sections separated by dots:
Header.Payload.Signature
For example:
xxxxx.yyyyy.zzzzz
The three parts are:
- Header
- Payload
- Signature
JWT Header
The header usually contains information about the token.
Example:
{
"alg": "RS256",
"typ": "JWT"
}
The alg field identifies the signing algorithm.
The exact algorithm depends on the authentication system.
JWT Payload
The payload contains claims.
Example:
{
"sub": "12345",
"name": "John",
"role": "user",
"exp": 1780000000
}
Common claims can include:
sub → Subject/user identifier
iss → Issuer
aud → Audience
exp → Expiration time
iat → Issued-at time
Applications can also have custom claims.
However, JWT payloads are encoded, not encrypted by default.
Therefore, don’t put sensitive information such as passwords or private secrets inside a JWT payload.
JWT Signature
The signature helps the server verify that the token has not been modified.
Conceptually:
Header
+
Payload
↓
Signing Process
↓
Signature
The exact cryptographic process depends on the signing algorithm.
Access Token vs Refresh Token
Modern authentication systems often use two types of tokens:
Access Token
Refresh Token
They have different purposes.
What Is an Access Token?
An access token is used to access protected APIs.
For example:
GET /profile
The request may include:
Authorization: Bearer <access-token>
The server validates the access token before returning protected data.
What Is a Refresh Token?
A refresh token is generally used to obtain a new access token after the current access token expires.
For example:
Access Token
↓
Expires
↓
Refresh Token
↓
New Access Token
This allows users to remain logged in without entering their password every time the access token expires.
Why Use Short-Lived Access Tokens?
A common security approach is to make access tokens relatively short-lived.
For example:
Access Token
→ Short lifetime
Refresh Token
→ Longer lifetime
If an access token is compromised, its useful lifetime is limited.
The exact expiration times should be chosen based on your application’s security requirements.
Complete Login Flow
A typical KMP authentication flow looks like:
User Opens App
↓
Check Stored Authentication State
↓
Is Session Available?
↓
Yes ─────────→ Home Screen
|
No
↓
Login Screen
↓
Email + Password
↓
Ktor Client
↓
POST /login
↓
Backend
↓
Validate Credentials
↓
Access Token + Refresh Token
↓
Secure Token Storage
↓
Authenticated Session
↓
Home Screen
Example Login Request
Suppose your backend exposes:
POST /auth/login
The request could contain:
{
"email": "john@example.com",
"password": "password123"
}
Your Kotlin model could be:
@Serializable
data class LoginRequest(
val email: String,
val password: String
)
Login Response Model
Suppose the backend returns:
{
"accessToken": "access-token",
"refreshToken": "refresh-token",
"expiresIn": 900
}
You can represent it using:
@Serializable
data class LoginResponse(
val accessToken: String,
val refreshToken: String,
val expiresIn: Long
)
The exact response fields depend on your backend.
Creating an Authentication API
With Ktor Client, your API service might look like:
class AuthApi(
private val client: HttpClient
) {
suspend fun login(
request: LoginRequest
): LoginResponse {
return client
.post("/auth/login") {
contentType(ContentType.Application.Json)
setBody(request)
}
.body()
}
}
This API service can be placed inside commonMain.
Authentication Repository
The repository should coordinate the authentication process.
Example:
class AuthRepository(
private val authApi: AuthApi,
private val tokenStorage: TokenStorage
) {
suspend fun login(
email: String,
password: String
) {
val response = authApi.login(
LoginRequest(
email = email,
password = password
)
)
tokenStorage.saveTokens(
accessToken = response.accessToken,
refreshToken = response.refreshToken
)
}
}
This separates API communication from application logic.
Why Use a Repository?
Without a repository:
UI
↓
Ktor
↓
API
The UI becomes tightly connected to networking.
A better architecture is:
UI
↓
ViewModel
↓
Repository
↓
Auth API
↓
Ktor
↓
Backend
This makes the application easier to:
- Test
- Maintain
- Extend
- Refactor
Where Should Tokens Be Stored?
This is one of the most important parts of mobile authentication.
You should not store authentication tokens in plain text files or ordinary unprotected preferences when stronger secure storage is available.
Instead, use platform-secure storage.
Conceptually:
Android
→ Android Keystore-backed secure storage
iOS
→ Apple Keychain
The exact implementation can be exposed to shared KMP code through an abstraction.
Creating a Token Storage Interface
You can define an abstraction in commonMain.
For example:
interface TokenStorage {
suspend fun saveTokens(
accessToken: String,
refreshToken: String
)
suspend fun getAccessToken(): String?
suspend fun getRefreshToken(): String?
suspend fun clear()
}
Then provide platform-specific implementations.
commonMain
|
TokenStorage
|
+---+---+
| |
Android iOS
| |
Keystore Keychain
This is a common KMP pattern.
Why Use expect and actual?
Kotlin Multiplatform provides expect and actual mechanisms for platform-specific implementations.
For example, shared code can define what functionality is required, while platform-specific source sets provide the implementation.
Conceptually:
commonMain
↓
expect SecureStorage
↓
+----------+
| |
androidMain iosMain
↓ ↓
actual actual
This approach is useful when secure storage requires native platform APIs.
Adding the Access Token to API Requests
After login, protected API requests need the access token.
For example:
Authorization: Bearer <access-token>
A simple Ktor request can be:
client.get("/profile") {
bearerAuth(accessToken)
}
The exact authentication configuration depends on your Ktor version and architecture.
For a larger application, you generally want this behavior centralized rather than repeated manually.
Centralizing Bearer Authentication
Instead of:
client.get("/profile") {
bearerAuth(token)
}
client.get("/orders") {
bearerAuth(token)
}
client.get("/products") {
bearerAuth(token)
}
you can configure Ktor authentication support so that protected requests use the current credentials.
Conceptually:
Ktor Client
↓
Authentication
↓
Access Token
↓
Protected API
This reduces duplication.
Ktor Bearer Authentication
Ktor Client provides authentication support for bearer tokens.
A simplified configuration can look like:
install(Auth) {
bearer {
loadTokens {
BearerTokens(
accessToken = tokenStorage.getAccessToken() ?: "",
refreshToken = tokenStorage.getRefreshToken() ?: ""
)
}
}
}
For a production implementation, don’t return an empty access token as a substitute for missing credentials. Your authentication flow should explicitly handle the unauthenticated state.
Refreshing an Expired Access Token
Suppose a request is made:
GET /profile
The server responds:
401 Unauthorized
because the access token has expired.
The client can then:
Request
↓
401
↓
Refresh Token
↓
POST /auth/refresh
↓
New Access Token
↓
Retry Original Request
This is commonly called token refresh.
Refresh API Example
Suppose your backend provides:
POST /auth/refresh
Request:
{
"refreshToken": "refresh-token"
}
Model:
@Serializable
data class RefreshTokenRequest(
val refreshToken: String
)
Response:
{
"accessToken": "new-access-token",
"expiresIn": 900
}
Model:
@Serializable
data class RefreshTokenResponse(
val accessToken: String,
val expiresIn: Long
)
Refreshing Tokens With Ktor
Ktor’s bearer authentication support can be configured to refresh credentials.
Conceptually:
install(Auth) {
bearer {
loadTokens {
val access = tokenStorage.getAccessToken()
val refresh = tokenStorage.getRefreshToken()
if (access != null && refresh != null) {
BearerTokens(
accessToken = access,
refreshToken = refresh
)
} else {
null
}
}
refreshTokens {
val refreshToken = tokenStorage.getRefreshToken()
?: return@refreshTokens null
val response = client.post("/auth/refresh") {
contentType(ContentType.Application.Json)
setBody(
RefreshTokenRequest(refreshToken)
)
}.body<RefreshTokenResponse>()
tokenStorage.saveAccessToken(
response.accessToken
)
BearerTokens(
accessToken = response.accessToken,
refreshToken = refreshToken
)
}
}
}
The exact API and configuration should be checked against the Ktor version used by your project.
Important Refresh Token Consideration
Don’t assume every backend returns a new refresh token.
Some systems return:
New Access Token
while others rotate both:
New Access Token
New Refresh Token
If your backend rotates refresh tokens, update both values atomically in secure storage.
Refresh Token Rotation
A more secure authentication system may rotate refresh tokens.
The flow becomes:
Old Refresh Token
↓
Refresh Request
↓
New Access Token
+
New Refresh Token
↓
Invalidate Old Refresh Token
If a stolen refresh token is reused, the backend can detect suspicious behavior depending on its token-rotation strategy.
The server must ultimately enforce refresh-token validity; the client cannot make a stolen token safe by itself.
Logout Flow
Logout should clear the locally stored authentication state.
Basic flow:
User taps Logout
↓
Optional server logout/revoke request
↓
Clear access token
↓
Clear refresh token
↓
Clear relevant user session data
↓
Login Screen
Example:
suspend fun logout() {
tokenStorage.clear()
}
If the backend supports token revocation or session invalidation, call that endpoint as part of logout where appropriate.
Should Logout Always Call the Server?
It depends on your authentication design.
For purely local session removal:
Clear local tokens
may be enough to log the user out from that device.
If the backend supports session/token revocation, server-side logout can provide stronger session control.
A robust design can use both.
Authentication State
Your application needs to know whether the user is:
Authenticated
Unauthenticated
Loading
A sealed hierarchy can represent this:
sealed interface AuthState {
data object Loading : AuthState
data object Unauthenticated : AuthState
data class Authenticated(
val userId: String
) : AuthState
}
Your UI can then react to the current state.
App Startup Authentication Check
When the application starts:
App Start
↓
Load Stored Tokens
↓
Are Tokens Available?
↓
No → Login
|
Yes
↓
Validate Session / Call Refresh if necessary
↓
Authenticated
↓
Home Screen
Don’t assume that simply having a locally stored token means the session is still valid.
The access token may have expired or the refresh token may have been revoked.
Token Expiration
JWT access tokens often contain an exp claim.
For example:
{
"sub": "12345",
"exp": 1780000000
}
The exp value represents the expiration time according to JWT conventions.
However, the server should remain the ultimate authority for token validity.
A client-side expiration check can help decide whether a refresh should be attempted, but it should not replace server-side validation.
JWT Is Not a Password
A JWT should not be treated like a user’s password.
Passwords should be:
- Sent only over secure connections
- Handled by the authentication backend
- Stored securely on the server using appropriate password hashing
The mobile application should not store the user’s password after login simply to keep them authenticated.
Instead:
Password
↓
Login
↓
Tokens
↓
Secure Token Storage
KMP Authentication Architecture
A clean project structure can look like:
shared/
│
└── src/
│
├── commonMain/
│ │
│ ├── data/
│ │ ├── network/
│ │ │ ├── HttpClientFactory.kt
│ │ │ └── AuthApi.kt
│ │ │
│ │ ├── model/
│ │ │ ├── LoginRequest.kt
│ │ │ ├── LoginResponse.kt
│ │ │ └── RefreshTokenResponse.kt
│ │ │
│ │ ├── repository/
│ │ │ └── AuthRepositoryImpl.kt
│ │ │
│ │ └── storage/
│ │ └── TokenStorage.kt
│ │
│ ├── domain/
│ │ ├── repository/
│ │ │ └── AuthRepository.kt
│ │ │
│ │ └── model/
│ │ └── AuthState.kt
│ │
│ └── presentation/
│ └── AuthViewModel.kt
│
├── androidMain/
│ └── storage/
│ └── AndroidSecureStorage.kt
│
└── iosMain/
└── storage/
└── IosKeychainStorage.kt
Your exact architecture can differ, but this separation keeps responsibilities clear.
Complete Authentication Data Flow
A production-oriented KMP authentication flow can look like:
Login Screen
|
↓
AuthViewModel
|
↓
AuthRepository
|
↓
AuthApi
|
↓
Ktor Client
|
↓
Login API
|
↓
Backend
|
↓
Access + Refresh Tokens
|
↓
Secure Token Storage
|
↓
Authenticated State
|
↓
Home
For protected API calls:
Home Screen
↓
Repository
↓
Ktor Client
↓
Access Token
↓
Backend
↓
200 OK
If the access token expires:
API Request
↓
401 Unauthorized
↓
Refresh Token
↓
Refresh API
↓
New Access Token
↓
Retry Request
↓
Success
Handling Refresh Failures
What happens if the refresh token is also invalid?
For example:
API Request
↓
401
↓
Refresh Token
↓
Refresh Failed
↓
Session Expired
↓
Clear Tokens
↓
Login Screen
The application should not endlessly retry.
A common rule is:
Original request
↓
Try refresh once
↓
Retry once
↓
If refresh fails
↓
Logout
The exact strategy depends on the backend.
Avoiding Infinite Refresh Loops
Consider:
Request
↓
401
↓
Refresh
↓
401
↓
Refresh
↓
401
↓
...
This can create an infinite loop.
Your authentication layer should ensure that a refresh request itself does not trigger another refresh cycle and that each failed request has a bounded retry path.
Handling Multiple Requests at the Same Time
Imagine five API requests happen simultaneously:
Request A → 401
Request B → 401
Request C → 401
Request D → 401
Request E → 401
You don’t want all five requests to independently refresh the token.
A better approach is to coordinate refresh operations:
Request A ─┐
Request B ─┤
Request C ─┼→ One Refresh Request
Request D ─┤
Request E ─┘
↓
New Access Token
↓
Retry Waiting Requests
This requires synchronization and careful concurrency handling.
It is especially important in applications that make many simultaneous API calls.
Authentication With KMP and Compose
If you are using Jetpack Compose on Android and Compose Multiplatform or another UI technology on other targets, the authentication logic can remain in the shared layer.
For example:
Android Compose
|
iOS UI / Compose Multiplatform
|
↓
Shared ViewModel / State
↓
Auth Repository
↓
Ktor
The UI technology doesn’t need to own the authentication implementation.
Authentication and Clean Architecture
KMP authentication works well with Clean Architecture.
A common structure is:
Presentation
↓
Domain
↓
Data
Presentation
Contains:
- Screens
- ViewModels
- UI state
Domain
Contains:
- Use cases
- Repository interfaces
- Business rules
Data
Contains:
- API services
- DTOs
- Ktor
- Token storage
- Repository implementations
This separation keeps authentication easier to maintain.
Security Best Practices for KMP Authentication
Authentication isn’t only about implementing login.
Security must be considered throughout the entire application.
1. Always Use HTTPS
Never send login credentials or authentication tokens over plain HTTP in production.
Use:
https://
instead of:
http://
2. Don’t Store Tokens in Plain Text
Use secure platform storage.
Android → Keystore-backed solution
iOS → Keychain
3. Never Hardcode Secrets
Don’t put:
Private API keys
Database passwords
Signing secrets
Backend credentials
inside the mobile application.
Anything embedded in a client application should be considered potentially discoverable.
4. Don’t Store Passwords
After successful login, don’t save the user’s password just to keep them logged in.
Use a proper session/token system.
5. Keep Access Tokens Short-Lived
Short-lived access tokens can reduce the impact of token exposure.
6. Protect Refresh Tokens
Refresh tokens generally provide longer-lived access and therefore require particularly careful storage and handling.
7. Don’t Log Authentication Tokens
Avoid logging:
Authorization headers
Access tokens
Refresh tokens
Passwords
even during development if those logs could leave the development environment.
8. Validate Tokens on the Server
The server must validate:
- Signature
- Expiration
- Issuer where applicable
- Audience where applicable
- Required claims
- Authorization/permissions
Never rely only on client-side checks.
JWT Security: Important Considerations
JWT is a token format, not a complete authentication system.
A secure authentication system also requires decisions about:
- Token lifetime
- Signing algorithm
- Key management
- Refresh token strategy
- Token revocation
- Session management
- Secure storage
- TLS
- Authorization
- Backend validation
Simply using JWT does not automatically make an application secure.
Common KMP Authentication Mistakes
Mistake 1: Storing Tokens in Normal Preferences
Avoid storing long-lived sensitive tokens in ordinary unprotected storage.
Use platform-secure storage where appropriate.
Mistake 2: Sharing the Wrong Things
KMP is about sharing code, not forcing every platform detail into shared code.
Keep platform-specific security APIs behind abstractions.
Mistake 3: Hardcoding API Secrets
Never put private server credentials into KMP source code.
Mistake 4: Refreshing Forever
Always place limits on refresh/retry operations.
Mistake 5: Trusting the Client
The server should always enforce authentication and authorization.
Mistake 6: Putting Sensitive Data in JWT Payloads
JWT payloads are normally readable by anyone who possesses the token.
Don’t treat the payload as encrypted storage.
KMP Authentication Testing
Authentication should be tested at several levels.
Unit Tests
Test:
- Login success
- Login failure
- Token storage
- Logout
- Refresh behavior
- Error mapping
Repository Tests
Test:
Login
↓
Save Tokens
↓
Authenticated State
Networking Tests
Test:
200
401
403
500
Timeout
No Internet
Refresh Tests
Test:
Access token expired
↓
Refresh succeeds
↓
Original request succeeds
And:
Access token expired
↓
Refresh fails
↓
Session cleared
Example End-to-End Authentication Flow
Imagine a user opens your shopping application.
Step 1: App Starts
App
↓
Check Secure Storage
Step 2: No Valid Session
No valid tokens
↓
Login Screen
Step 3: User Logs In
Email + Password
↓
POST /auth/login
Step 4: Server Responds
Access Token
Refresh Token
Step 5: Store Tokens
Secure Storage
Step 6: Fetch Profile
GET /profile
Authorization: Bearer <access-token>
Step 7: Access Token Expires
GET /orders
↓
401
Step 8: Refresh
POST /auth/refresh
↓
New Access Token
Step 9: Retry
GET /orders
↓
200 OK
Step 10: Logout
Logout
↓
Optional server-side session/token revocation
↓
Clear local authentication state
↓
Login Screen
Recommended KMP Authentication Architecture
For a production KMP application, a practical architecture is:
┌───────────────────────────────┐
│ Android UI │
└───────────────┬───────────────┘
│
┌───────────────▼───────────────┐
│ iOS UI │
└───────────────┬───────────────┘
│
▼
Shared Presentation
│
▼
Auth ViewModel
│
▼
Auth Use Case
│
▼
Auth Repository
│
▼
Auth API
│
▼
Ktor HttpClient
│
┌───────┴────────┐
│ │
Access Token Refresh Token
│ │
└───────┬────────┘
│
Secure Token Storage
│ │
Android iOS
Keystore Keychain
│
▼
Backend API
This architecture provides a clear separation between:
- UI
- Business logic
- API communication
- Authentication
- Token management
- Platform-specific secure storage
Frequently Asked Questions
What is JWT authentication?
JWT authentication is a token-based authentication approach where a signed JWT can be presented to a server to authenticate API requests.
Can Kotlin Multiplatform share authentication code?
Yes. API models, networking, repositories, authentication state, and much of the token-management logic can be shared between platforms.
Can Ktor handle JWT authentication?
Yes. Ktor Client provides authentication support that can be used with bearer tokens and token refresh flows.
Where should JWT tokens be stored in KMP?
Sensitive tokens should be stored using secure platform-specific storage, such as an Android Keystore-backed solution or iOS Keychain.
Should I store the JWT in SharedPreferences?
For sensitive long-lived authentication credentials, plain application preferences are generally not the preferred secure storage mechanism. Use an appropriate secure-storage solution.
What happens when an access token expires?
The client can use a valid refresh token to request a new access token, then retry the original API request. If refresh fails, the application should end the authenticated session.
Can I use JWT without a refresh token?
Yes. Some systems use only access tokens. However, users may need to authenticate again when those tokens expire unless another session mechanism is provided.
Should JWT contain user passwords?
Absolutely not. Passwords should never be stored inside JWT payloads.
Is JWT encrypted?
Normally, no. A signed JWT provides integrity/authenticity properties, but its payload is generally readable. Encryption requires a different mechanism such as an encrypted token format.
Can KMP authentication work with Android and iOS?
Yes. KMP can share authentication and networking logic while using platform-specific secure storage and other native capabilities where required.
Conclusion
Authentication is a critical part of almost every modern mobile application, and Kotlin Multiplatform provides a strong foundation for sharing authentication logic between Android and iOS.
Using Ktor Client, Kotlin Serialization, repositories, and platform-secure token storage, you can build a reusable authentication architecture.
The overall flow can be summarized as:
Login
↓
Backend Validation
↓
Access + Refresh Tokens
↓
Secure Storage
↓
Authenticated API Requests
↓
Access Token Expires
↓
Refresh Token
↓
New Access Token
↓
Retry Request
The most important principles are:
- Share authentication logic where practical.
- Keep platform-specific secure storage behind abstractions.
- Use HTTPS for all production authentication traffic.
- Store tokens securely.
- Never store passwords for session persistence.
- Keep access tokens reasonably short-lived.
- Protect refresh tokens carefully.
- Prevent infinite refresh loops.
- Coordinate concurrent refresh requests.
- Don’t place sensitive secrets in JWT payloads.
- Always enforce authentication and authorization on the server.
Kotlin Multiplatform does not require Android and iOS to have identical implementations of everything. Instead, it lets you share the core networking, authentication, and business logic while allowing each platform to use its own secure native capabilities.
That combination makes KMP a practical choice for building secure cross-platform applications with a shared authentication layer.
