Session and Token Lifecycle

The Entrupy Android SDK manages user sessions through a secure token-based authentication system. Understanding how sessions work and when they expire is crucial for maintaining a smooth user experience.

Session Overview

When a user successfully authorizes with the Entrupy SDK, a session is created that allows the SDK to communicate with Entrupy's backend services. This session is tied to:

• The specific user (via unique_user_id)
• Your application (via API key)
• A time-limited token

Token Expiration

SDK authorization tokens have a limited lifespan for security reasons. The exact expiration time varies but is typically:

• Default expiration: 24 hours from creation
• Maximum expiration: 7 days (configurable by Entrupy)

Checking Session Status

Before performing any SDK operations, always verify that the current session is valid:

import com.entrupy.sdk.app.EntrupyApp

val entrupyApp = EntrupyApp.sharedInstance()
val isAuthorized = entrupyApp.isAuthorizationValid()

if (isAuthorized) {
    // Proceed with SDK operations
    startCaptureFlow()
} else {
    // Re-authorize the user
    performUserAuthorization()
}

Session Expiration Handling

When a session expires, the SDK will automatically invalidate it. Your app should handle this gracefully:

1. Detect Expiration

import com.entrupy.sdk.app.EntrupyApp

val entrupyApp = EntrupyApp.sharedInstance()

// Check before each SDK operation
if (!entrupyApp.isAuthorizationValid()) {
    // Session has expired
    handleSessionExpiration()
}

2. Re-authorize the User

When a session expires, you must go through the full authorization flow again:

import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.listeners.SdkLoginCallback

private fun handleSessionExpiration() {
    val entrupyApp = EntrupyApp.sharedInstance()
    
    // 1. Generate new authorization request
    val authRequest = entrupyApp.generateSDKAuthorizationRequest()
    
    // 2. Send to your backend
    yourBackendService.authorizeUser(authRequest) { signedRequest ->
        // 3. Login with new token
        entrupyApp.loginUser(
            signedRequest = signedRequest,
            callback = object : SdkLoginCallback {
                override fun onLoginStarted() {
                    // Show loading indicator
                }
                
                override fun onLoginSuccess(expirationTime: Long) {
                    // Session renewed successfully
                    continueWithOriginalOperation()
                }
                
                override fun onLoginError(
                    errorCode: Int,
                    description: String,
                    localizedDescription: String
                ) {
                    // Handle re-authorization failure
                    showErrorToUser(localizedDescription)
                }
            }
        )
    }
}

Proactive Token Refresh

For better user experience, consider implementing proactive token refresh:

1. Store Expiration Time

When a user successfully logs in, store the expiration timestamp:

import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.listeners.SdkLoginCallback

val entrupyApp = EntrupyApp.sharedInstance()

entrupyApp.loginUser(signedRequest, object : SdkLoginCallback {
    override fun onLoginStarted() {
        // Show loading
    }
    
    override fun onLoginSuccess(expirationTime: Long) {
        // Store for proactive refresh
        sharedPreferences.edit()
            .putLong("entrupy_token_expiry", expirationTime)
            .apply()
    }
    
    override fun onLoginError(
        errorCode: Int,
        description: String,
        localizedDescription: String
    ) {
        // Handle failure
    }
})

2. Check Before Operations

private fun checkTokenExpiry() {
    val storedExpiry = sharedPreferences.getLong("entrupy_token_expiry", 0L)
    val currentTime = System.currentTimeMillis()
    val bufferTime = 5 * 60 * 1000 // 5 minutes buffer
    
    if (currentTime > (storedExpiry - bufferTime)) {
        // Token will expire soon, refresh proactively
        refreshUserAuthorization()
    }
}

Session Security

Token Storage

The SDK handles token storage internally and securely. You should not:

• Store tokens in plain text
• Log tokens to console
• Transmit tokens over insecure channels

Best Practices

1. Always verify authorization before SDK operations
2. Handle expiration gracefully with user-friendly messages
3. Implement proactive refresh for better UX
4. Log out users when they explicitly sign out of your app
5. Clear stored data when users uninstall or reset your app

Logout and Session Cleanup

When a user logs out of your app, you should clear the SDK session:

import com.entrupy.sdk.app.EntrupyApp

fun logoutUser() {
    val entrupyApp = EntrupyApp.sharedInstance()
    
    // Clear SDK session
    entrupyApp.cleanup()
    
    // Clear stored expiration time
    sharedPreferences.edit()
        .remove("entrupy_token_expiry")
        .apply()
    
    // Clear other app-specific data
    clearUserData()
}

Error Handling

Common session-related errors include:

• UNAUTHORIZED_ACCESS (401): Token has expired or is invalid
• FORBIDDEN (403): User does not have permission
• SERVICE_UNAVAILABLE (503): Unable to communicate with Entrupy servers
• SDK_NOT_INITIALIZED (2002): SDK was not initialized before use

Handle these errors appropriately in your app's UI and provide clear guidance to users.