Skip to main content

C. SDK User Authorization

Important

User authorization is required before Entrupy SDK operations can be performed: this includes initiating an authentication capture, searching submissions, or any other SDK function that interacts with the Entrupy platform.

To use the services provided by the Entrupy iOS SDK, your application must obtain and maintain a valid authorization token for the end-user. This token secures the communication between the SDK running in your app and the Entrupy backend.

Authorization tokens have an expiration time. Your application is responsible for re-creating tokens when they expire. It is highly recommended to check token validity and re-authorize if necessary before calling other SDK methods to avoid errors and additional latency.

The authorization process involves a client-side step (your app) and a server-side step (your backend).

1. Authorization Flow Overview​

  1. Client-Side (Your App): Generate SDK Authorization Request. Your iOS application uses an SDK method to generate a unique request string.
  2. Server-Side (Your Backend): Sign Authorization Request. Your app sends this request string to your backend. Your backend then validates the end-user (based on your own authentication system) and forwards the request string, along with your user's details, to the Entrupy API for signing.
  3. Server-Side (Entrupy API): Issue Signed Request. The Entrupy API validates your backend's request, associates the end-user with your organization, and returns a signed_authorization_request to your backend.
  4. Server-Side (Your Backend): Return Signed Request to App. Your backend relays this signed_authorization_request back to your iOS application.
  5. Client-Side (Your App): Log In to SDK. Your app uses the signed_authorization_request to log in to the Entrupy SDK, establishing an authorized session.
  6. Client-Side (Your App): Manage Token Lifecycle. Your app needs to be aware of the token's expiration and re-initiate this flow when the token is about to expire.

2. Create SDK Authorization Request (Client-Side)​

Your iOS app initiates the process by generating an SDK authorization request string.

import EntrupySDK

func getSDKAuthRequestString() -> String? {
    // This method generates a string to be passed to your app's backend for signing.
    let sdkAuthorizationRequest = EntrupyApp.sharedInstance().generateSDKAuthorizationRequest()
    return sdkAuthorizationRequest
}

// Example usage:
if let requestString = getSDKAuthRequestString() {
    // Send requestString to your backend (see Step 2)
}

3. Process and Sign Request (Your Backend)​

Your application sends the sdkAuthorizationRequest string (obtained in Step 2) to your backend server. Your backend should have a secure endpoint (e.g., /authorize-entrupy-sdk-user) that performs the following:

  1. Authenticate Your User: Verify the identity of the user making the request, typically using your existing session management or token system.

  2. Prepare Data for Entrupy API: Gather necessary user information. At a minimum, this includes a unique_user_id (an ID you manage for your user) and their email. Optional fields like first_name and last_name can also be provided for use on certificates.

  3. Call Entrupy API to Sign the Request: Your backend makes a server-to-server POST request to the Entrupy API endpoint /v2/integrations/authorize-user.

    For detailed information on this backend integration, including request/response formats, parameters, and error handling, refer to the Essential Backend Integration Tasks document.

    A conceptual example of the request your backend sends to Entrupy API:

    POST /v2/integrations/authorize-user HTTP/1.1
    Host: api.entrupy.com
    Authorization: Token YOUR_ENTRUPY_API_TOKEN
    Content-Type: application/json

    {
      "sdk_authorization_request": "<the_string_from_your_app>",
      "unique_user_id": "your_internal_user_id_123",
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }

  4. Receive Signed Request: The Entrupy API will respond with a JSON payload containing the signed_authorization_request and a username (an Entrupy-generated username for that user, like YourOrgName-your_internal_user_id_123).

  5. Return to App: Your backend sends the signed_authorization_request string back to your iOS application.

4. Log In to SDK (Client-Side)​

Once your app receives the signed_authorization_request from your backend, it uses this to log in to the Entrupy SDK.

First, ensure your relevant class (e.g., your UIViewController or a dedicated manager class) conforms to the EntrupyLoginDelegate protocol.

import EntrupySDK

class YourViewController: UIViewController { // Or your relevant class
    // ... your existing code ...

    func loginToEntrupySDK(signedRequest: String) {
        EntrupyApp.sharedInstance().loginDelegate = self
        EntrupyApp.sharedInstance().loginUser(withSignedRequest: signedRequest)
    }
}

extension YourViewController: EntrupyLoginDelegate {
    // Invoked if the login was successful
    // Save the received authorization token expiry timestamp. You might store this
    // in UserDefaults or a secure keychain to check before subsequent SDK calls.
    func didLoginUserSuccessfully(_ expirationTime: TimeInterval) {
        print("Entrupy SDK login successful. Token expires at: \(Date(timeIntervalSince1970: expirationTime))")
        // Store expirationTime securely
        // e.g., UserDefaults.standard.set(expirationTime, forKey: "entrupyTokenExpiry")
    }

    // Invoked if the login was unsuccessful
    func didLoginUserFailWithError(_ errorCode: EntrupyErrorCode, description: String, localizedDescription: String) {
        print("Entrupy SDK login failed. Error: \(localizedDescription) (Code: \(errorCode))")
        // Handle the error appropriately:
        // - Inform the user.
        // - Log the error for debugging.
        // - Potentially disable SDK-dependent features.
        // Refer to the Error Code Reference for details on specific error codes.
    }
}

Example of initiating login after receiving the signed request from your backend:

// Assuming 'signedAuthRequestFromServer' is the string received from your backend
// and 'self' is an instance of YourViewController (or your delegate class)

// In your network response handler from your backend:
self.loginToEntrupySDK(signedRequest: signedAuthRequestFromServer)

5. Checking Token Validity​

Before making SDK calls (like starting a capture flow), you should check if the current SDK authorization token is still valid. This prevents errors and ensures a smooth user experience.

import EntrupySDK

func isUserAuthorized() -> Bool {
    if EntrupyApp.sharedInstance().isAuthorizationValid() {
        // Optionally, you can also check your stored expirationTime against the current time
        // for an extra layer of verification or to proactively re-authorize.
        // let storedExpiry = UserDefaults.standard.double(forKey: "entrupyTokenExpiry")
        // if Date().timeIntervalSince1970 < storedExpiry - 60 { /* 60s buffer */
        //     return true
        // }
        return true
    } else {
        return false
    }
}

// Example Usage:
if !isUserAuthorized() {
    // Initiate the re-authorization process (Steps 1-3)
}
// Proceed with SDK operation (e.g., start capture)

If isAuthorizationValid() returns false, or if your own check against the stored expirationTime indicates expiry, you must repeat the authorization process (Steps 2-4) to obtain a new token before proceeding with other SDK operations.