​
Introduction

Boxo Connect is a Single Sign-On (SSO) functionality that enables the host app to securely pass user profile information, allowing seamless authorization within the mini app. In essence, the Boxo Platform facilitates the transfer of user data from the host app backend to the mini app backend, ensuring smooth user authentication and returning a session token for continued access.

​
Boxo Connect flow

Here is diagram showcasing the hostapp user authorization inside miniapp AuthDiagram Authentication and User Authorization Flow
  1. User launches miniapp: The user opens the host app and launches the miniapp.
  2. Miniapp identifies the user and proceeds with the flow: The miniapp determines that user identification is needed to proceed.
  3. Miniapp calls appboxosdk.login JS SDK event: The miniapp requests a login action via Boxo’s JavaScript SDK.
  4. Consent screen is shown to the user: The user sees a consent dialog asking to “Allow miniapp to access your account information” with an “Allow” button.
  5. User makes a request to Super App’s Auth Gateway: After user consent, the system makes a request to the host app’s authentication gateway.
  6. Super App Server sends user data to Boxo Platform: The host app backend sends the user data to the Boxo Platform connect/ endpoint.
  7. Boxo Platform sends user data to Miniapp Server: The Boxo Platform forwards the user data to the miniapp backend.
  8. Miniapp Server generates authToken for user data: The miniapp backend processes the user data and generates an authorization token.
  9. authToken is returned to Super App: The token is also provided back to the host app.
  10. authToken is returned to miniapp: The authorization token is sent back through the chain to the miniapp frontend.
  11. User is authorized in miniapp server: The miniapp server authorizes the user using the token.
  12. User proceeds with the flow: The user is successfully authorized and can continue using the miniapp.
This process ensures a secure and seamless flow for user authorization between the host app, Boxo platform, and miniapp.

​
Setting up the backend

*Note: Feature must be enabled in Dashboard Partnership AuthDiagram Data format Currently, data exchange is conducted in JSON format. String size limits are defined within the respective data types.

​
Connect endpoint

This endpoint is called by the Super App (partner) server to connect a user to a miniapp on the Boxo Platform. On success, it returns an authorization token pair for the miniapp session. URL and METHOD
  • HTTPS POST /api/v1/connect/ (Boxo Platform)
Headers
KeyValue
Content-typeapplication/json
Authentication to this endpoint is managed via your partnership configuration in the Dashboard (e.g., IP whitelisting or Request Signaturing). Follow your integration setup.
Request Body
FieldData typeOptionalDescription
client_idStringNoHostapp identifier
app_idStringNoMiniapp identifier
user_dataUserDataNoUser information object
UserData
FieldData typeOptionalDescription
referenceStringNoReference to user in Hostapp Server
emailStringYesVerified user email address
phoneStringYesVerified user phone number in E.164 format
first_nameStringYesUser’s first name
last_nameStringYesUser’s last name
custom_attributesJSONYesCustom attributes
Response
  • Response status 200 for success, 400 for errors
  • Response body:
Success Response (200):
FieldData typeDescription
tokenStringAuth token
refresh_tokenStringRefresh token
Error Response (400):
FieldData typeOptionalDescription
error_codeStringNoError code
error_messageStringNoDetailed error message
exceptionStringYesException details if available
custom_attributesObjectYesAdditional error context
Request Example 
curl --location --request POST '[BOXO_PLATFORM_SERVER_URL]/api/v1/connect/' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "client_id": "{{CLIENT_ID}}",
    "app_id": "{{MINIAPP_ID}}",
    "user": {
      "reference": "{{USER_REFERENCE}}",
      "email": "john@example.com",
      "phone": "+11234567890",
      "first_name": "John",
      "last_name": "Doe",
      "custom_attributes": {}
    }
  }'
WARNING For Shopboxo miniapps either email or phone must be provided
Success Response (200) 
{
  "token": "<AUTH_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>"
}
Error Response (400) 
{
  "error_code": "INVALID_INPUT",
  "error_message": "Missing required field: app_id",
  "exception": null,
  "custom_attributes": null
}
Required fields Each mini app requires a set of minimum fields to create a user within its system and generate a session for the newly created user. The specific required fields for each mini app can be found in its details on the Showroom page. Below is a list of all possible fields:
  • email
  • phone
  • first_name
  • last_name
  • custom_attributes

​
Setting up the SDK

Initialization Parameter Descriptions: Within the SDK, there are specific parameters and methods that must be either provided or implemented to ensure proper functionality. app_id - Boxo miniapp app id To launch a specific mini app, you must first call the initialization method.

​
iOS

let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
miniapp.delegate = self
miniapp.open(viewController: self)
...
extension ViewController : MiniappDelegate {

    func onAuth(miniapp: Miniapp) {
        //send a request to backend to fetch tokens
        miniapp.setAuthTokens(["token" : "<token>", "refresh_token" : "<refresh_token>"])
    }
}

​
Android

val miniapp = Boxo.getMiniapp("app_id")
miniapp.setAuthListener { boxoActivity, miniapp ->
    //use boxoActivity to open dialogs or activity
    //send a request to backend to fetch tokens
    miniapp.setAuthTokens(mapOf(
        "token" to "<token>",
        "refresh_token" to "<refresh_token>"
    ))
}
miniapp.open(activity)

​
Flutter


Boxo.openMiniapp('app_id');
Boxo.lifecycleHooksListener(
    onAuth: (appId) { // called when authorization flow starts
        //send a request to backend to fetch tokens
        Boxo.setAuthTokens({
            'token': '<token>',
            'refresh_token': '<refresh_token>'
        });
    }
);

​
ReactNative

Boxo.openMiniapp('app_id')
Boxo.lifecycleHooksListener({
    onAuth: (appId: string) => {
        //send a request to backend to fetch tokens
        Boxo.setAuthTokens({
            'token': '<token>',
            'refresh_token': '<refresh_token>'
        });
    },    
});
WARNING When a user logs out of the host app, ensure that the WebView cache is cleared using the following commands: Boxo.logout() for Android or Boxo.shared.logout() for iOS so that the miniapps’ storage is also cleared to log out the miniapp users as well.
This is Boxo endpoint to get status of user consent in Boxo Platform URL and METHOD
  • This is HTTPS GET /api/v1/accounts/consent/get_consent/ endpoint

​
Query Parameters:

ParameterData typeOptionalDescription
client_idStringHostapp identifier
app_idStringMiniapp identifier
user_referenceStringReference to user in Hostapp Server
Response:
{
   “is_consented”: <Bool>
}