Skip to main content

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:

val isAuthorized = EntrupySdk.getInstance().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​

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

2. Re-authorize the User​

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

private fun handleSessionExpiration() {
    // 1. Generate new authorization request
    val authRequest = EntrupySdk.getInstance().generateAuthorizationRequest()
    
    // 2. Send to your backend
    yourBackendService.authorizeUser(authRequest) { signedRequest ->
        // 3. Login with new token
        EntrupySdk.getInstance().login(
            signedRequest = signedRequest,
            callback = object : EntrupyLoginCallback {
                override fun onSuccess(expirationTimestamp: Long) {
                    // Session renewed successfully
                    continueWithOriginalOperation()
                }
                
                override fun onFailure(errorCode: EntrupyErrorCode, message: String) {
                    // Handle re-authorization failure
                    showErrorToUser("Authentication failed. Please try again.")
                }
            }
        )
    }
}

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:

EntrupySdk.getInstance().login(signedRequest, object : EntrupyLoginCallback {
    override fun onSuccess(expirationTimestamp: Long) {
        // Store for proactive refresh
        sharedPreferences.edit()
            .putLong("entrupy_token_expiry", expirationTimestamp)
            .apply()
    }
    
    override fun onFailure(errorCode: EntrupyErrorCode, message: 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:

fun logoutUser() {
    // Clear SDK session
    EntrupySdk.getInstance().logout()
    
    // Clear stored expiration time
    sharedPreferences.edit()
        .remove("entrupy_token_expiry")
        .apply()
    
    // Clear other app-specific data
    clearUserData()
}

Error Handling​

Common session-related errors include:

  • AUTHORIZATION_EXPIRED: Token has expired
  • AUTHORIZATION_INVALID: Token is malformed or invalid
  • NETWORK_ERROR: Unable to communicate with Entrupy servers
  • USER_NOT_AUTHORIZED: No valid session exists

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