C. SDK User Authorization (Android)

⚠️ Important:

User authorization is required before using any Entrupy SDK operations — including launching a capture flow, searching submissions, or accessing results.

To secure communication between the Entrupy SDK and Entrupy's backend, your Android app must first authenticate each user session using a signed authorization token. Tokens expire after a set period, so your app is responsible for refreshing them as needed.

1. Authorization Flow Overview

The Entrupy SDK uses a client–server–client pattern for secure authorization. Here's how it works:

1.1. Client (Android App): Generate SDK Authorization Request

The Android app requests a raw SDK authorization string from the SDK.

1.2. Server (Your Backend): Sign Request

You send that string to your backend, which verifies the current user and calls Entrupy's API to generate a signed request.

1.3. Server (Entrupy): Returns a Signed Request

Entrupy returns a signed authorization payload and a platform username.

1.4. Server → Client: Return to Android App

Your backend sends the signed request back to the app.

1.5. Client (Android App): Log in to SDK

The SDK uses the signed request to log in and open a valid session.

2. Generate SDK Authorization Request (Client-Side)

To begin, generate a raw SDK authorization request string from the Entrupy SDK.

import com.entrupy.sdk.app.EntrupyApp

val entrupyApp = EntrupyApp.sharedInstance()
val authRequest = entrupyApp.generateSDKAuthorizationRequest()
// Send `authRequest` to your backend to proceed to Step 3

3. Sign the Request (Your Backend)

Your backend should expose a secure endpoint (e.g., /authorize-entrupy-sdk-user) that:

1. Authenticates your user (e.g., via session or token).

2. Receives the SDK request string from the app.

3. Calls Entrupy's API to sign the request:

   POST https://api.entrupy.com/v2/integrations/authorize-user
   Headers:
     Authorization: Token YOUR_ENTRUPY_API_TOKEN
     Content-Type: application/json
   
   Body:
   {
     "sdk_authorization_request": "<request_string_from_sdk>",
     "unique_user_id": "your_internal_user_id_123",
     "email": "user@example.com",
     "first_name": "John",
     "last_name": "Doe"
   }
   

4. Returns the signed request to your Android app:

{
  "signed_authorization_request": "signed-token-here",
  "username": "YourOrg-your_user_id"
}

4. Log in to SDK (Client-Side)

Once the app receives the signed_authorization_request, log in using the SDK. The callback parameter is optional.

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

val entrupyApp = EntrupyApp.sharedInstance()

entrupyApp.loginUser(
    signedRequest = signedRequestFromBackend,
    callback = object : SdkLoginCallback {
        override fun onLoginStarted() {
            Log.d("Entrupy", "Login process started")
            // Show loading indicator
        }

        override fun onLoginSuccess(expirationTime: Long) {
            Log.d("Entrupy", "Login successful. Token expires at: $expirationTime")
            // expirationTime is epoch milliseconds
            // Store expirationTime securely (e.g., in SharedPreferences)
        }

        override fun onLoginError(
            errorCode: Int,
            description: String,
            localizedDescription: String
        ) {
            Log.e("Entrupy", "Login failed. Error: $description (Code: $errorCode)")
            // Show localizedDescription to user for user-friendly messaging
            // Handle login failure (show UI message, retry, etc.)
        }
    }
)

✅ The SDK stores the active session internally. You may cache the expiration timestamp on your side as a backup to avoid redundant network calls.

5. Check Authorization Status

Before making any SDK calls (e.g., launching a capture flow), you should verify that the current session is still authorized.

import com.entrupy.sdk.app.EntrupyApp

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

If isAuthorizationValid() returns false, you must repeat the authorization flow to obtain a new token.

Optional: Expiry-Time Based Check

If you stored the expirationTime locally, you can add a buffer check:

val storedExpiry = sharedPrefs.getLong("entrupy_token_expiry", 0L)
val isStillValid = System.currentTimeMillis() < (storedExpiry - 60_000) // 1-minute buffer

6. Cleanup on Logout

When the user logs out of your application, clear the SDK's stored tokens and release resources:

import com.entrupy.sdk.app.EntrupyApp

val entrupyApp = EntrupyApp.sharedInstance()
entrupyApp.cleanup()

Summary of Developer Responsibilities

Step	Responsibility
1	Call generateSDKAuthorizationRequest() in your app
2	Send that to your backend
3	Backend authenticates and calls Entrupy API
4	Backend returns signed_authorization_request
5	Use EntrupyApp.sharedInstance().loginUser(...) to log in
6	Optionally store the expiration timestamp
7	Call isAuthorizationValid() before SDK operations
8	Call cleanup() when user logs out