Skip to main content

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:

  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.

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

StepResponsibility
1Call generateAuthorizationRequest() in your app
2Send that to your backend
3Backend authenticates and calls Entrupy API
4Backend returns signed_authorization_request
5Use EntrupySdk.getInstance().login(...) to log in
6Optionally store the expiration timestamp
7Call isAuthorizationValid() before SDK operations