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.
val authRequest = EntrupySdk.getInstance().generateAuthorizationRequest()
// 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:
-
Authenticates your user (e.g., via session or token).
-
Receives the SDK request string from the app.
-
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"
} -
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.
EntrupySdk.getInstance().login(
signedRequest = signedRequestFromBackend,
callback = object : EntrupyLoginCallback {
override fun onSuccess(expirationTimestamp: Long) {
Log.d("Entrupy", "Login successful. Token expires at: $expirationTimestamp")
// Store expirationTimestamp securely (e.g., in SharedPreferences)
}
override fun onFailure(errorCode: EntrupyErrorCode, message: String) {
Log.e("Entrupy", "Login failed. Error: $message (Code: $errorCode)")
// 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.
val isAuthorized = EntrupySdk.getInstance().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 expirationTimestamp
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
Summary of Developer Responsibilities
Step | Responsibility |
---|---|
1 | Call generateAuthorizationRequest() in your app |
2 | Send that to your backend |
3 | Backend authenticates and calls Entrupy API |
4 | Backend returns signed_authorization_request |
5 | Use EntrupySdk.getInstance().login(...) to log in |
6 | Optionally store the expiration timestamp |
7 | Call isAuthorizationValid() before SDK operations |