Essential Backend Integration Tasks

For a successful Entrupy iOS SDK integration, several important tasks must be implemented on your backend server. These tasks enable secure user authorization, allow you to manage and query authentication data, and receive real-time updates.

1. Signing SDK User Authorization Requests

Before any user can utilize the Entrupy SDK within your application, they must be authorized. This process involves your application requesting a signed authorization string from your backend, which in turn obtains this from the Entrupy API.

Workflow:

1. Client App Initiates Request:

   • Your iOS application generates an SDK authorization request string using EntrupyApp.sharedInstance().generateSDKAuthorizationRequest().

2. Backend Receives Request:

   • The client app sends this sdk_authorization_request string to a dedicated endpoint on your backend (e.g., /authorize-entrupy-sdk-user).
   • Your backend endpoint must first authenticate and authorize your user (e.g., by validating their session token for your platform).

3. Backend Signs Request via Entrupy API:

   • If your user is authorized, your backend server makes a POST request to the Entrupy API endpoint: /v2/integrations/authorize-user.
   • This request includes the sdk_authorization_request received from the client, along with user identifiers (unique_user_id, email, and optionally first_name, last_name).
     • unique_user_id: A unique identifier (8-40 chars, A-Za-z0-9@.+_-) for the user on your platform. This ID is important for associating the user with their Entrupy authentications.
     • email: The user's email address.
     • first_name, last_name: Optional, used for certificates. These are set permanently on the first call for a unique_user_id.
   • Your backend must include your organization's Entrupy API token in the Authorization header of this request.
   • Example Entrupy API Request from Your Backend:

     POST /v2/integrations/authorize-user HTTP/1.1
     Host: api.entrupy.com
     Accept-Language: en
     Authorization: Token [Your_Entrupy_API_Token]
     Content-Type: application/json
     
     {
       "sdk_authorization_request": "client_generated_sdk_auth_request_string",
       "unique_user_id": "your_platform_user_id_123",
       "email": "user@example.com",
       "first_name": "John",
       "last_name": "Doe"
     }
   • The Entrupy API will respond with a signed_authorization_request and an Entrupy username (e.g., YourOrganizationName-your_platform_user_id_123). Store this username as it's needed for backend searches.

4. Backend Returns Signed Request to Client:

   • Your backend sends the signed_authorization_request (obtained from the Entrupy API) back to your iOS application.

5. Client Logs In to SDK:

   • The iOS application uses this signed_authorization_request to log the user into the Entrupy SDK via EntrupyApp.sharedInstance().loginUser(withSignedRequest: signedRequest).

Important

The unique_user_id you provide is important for linking authentications back to your users. The Entrupy username returned by the /v2/integrations/authorize-user call should be stored on your backend, as it is often required for API operations like searching authentications performed by that specific user.

Refer to the main Entrupy API documentation for the most up-to-date details on the /v2/integrations/authorize-user endpoint, including error handling and parameter specifics.

2. Advanced Authentication Management via Entrupy API

Your backend server can use the Entrupy API for comprehensive management and querying of authentication data. This is essential for tasks beyond the direct user interactions handled by the SDK.

Key API Capabilities:

• Searching Authentications:
  • Retrieve a list of authentications, with powerful filtering capabilities.
  • You can search by the Entrupy username (associated with your unique_user_id), customer_item_id, date ranges, brand, result status, and other fields.
  • This is typically done using the search routes provided by the Entrupy API (e.g., POST /v2/search/authentications).
• Looking Up Specific Authentications:
  • Fetch detailed information for a single authentication, often using the customer_item_id you provided during submission or the Entrupy-generated session ID.
  • Use the lookup routes (e.g., GET /v2/lookup/authentications/{lookup_value} or GET /v2/authentications/{entrupy_id}).
• Accessing Detailed Results:
  • Obtain the full authentication result, including status, certificate information (if applicable), and any associated data like Catalog Data.

For complete details on available endpoints, request/response formats, and filtering options, consult the latest Entrupy API Reference documentation.

3. Configuring Webhooks for Real-Time Updates

To receive asynchronous notifications about authentication status changes (e.g., when a result is finalized or a flag is updated), you should configure webhooks via the Entrupy API.

How Webhooks Work:

1. Configuration: You register a webhook endpoint (a URL on your backend server) with Entrupy via an API call.
2. Event Occurs: When a relevant event happens for an authentication linked to your organization (e.g., an item's status changes from "pending" to "authentic"), Entrupy's system sends an HTTP POST request to your registered webhook URL.
3. Backend Processes Notification: Your backend receives this POST request, which contains a payload detailing the event and the affected authentication. Your system can then process this information, for example, by updating your internal database, notifying users, or triggering other workflows.

Webhooks are more efficient than polling as results are returned immediately with a lower system load.

Refer to the Webhook Configuration Guide for detailed instructions on:

• Registering and managing webhook endpoints.
• The structure of webhook event payloads.
• Security best practices (e.g., verifying webhook signatures).

By implementing these backend tasks, you create a robust and secure integration that fully utilizes the capabilities of the Entrupy iOS SDK and the Entrupy API platform.

• Webhooks for Real-Time Updates: Implement a webhook endpoint to receive real-time notifications from Entrupy for events such as authentication completion or new support messages. This facilitates timely updates to your users and backend systems. See the Webhook Configuration Guide for details.