Boxo Connect

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.

BoxoConnect OAuth
BoxoConnect Direct

This is the traditional OAuth flow where the host app backend provides auth codes and access tokens to the Boxo Platform.

OAuth Flow Diagram

Here is diagram showcasing the hostapp user authorization inside miniapp

Authentication and User Authorization Flow

User launches miniapp

The user opens the host app and launches the mini app.

User identification required

To proceed, the user must be identified (e.g., for product purchases or user registration).

Miniapp calls login

The mini app calls Boxo.login().

User consent

The user is prompted to confirm access to their personal data required for authorization.

SDK retrieves auth code

The Boxo native SDK retrieves an authorization code from the host app and sends an HTTPS request to the Boxo platform.

Platform forwards auth code

The Boxo platform forwards the authorization code via an HTTPS request to the host app backend.

Backend validates and returns access token

The host app backend validates the authorization code and returns an access token.

Platform requests user data

The Boxo platform sends an HTTPS request with the access token to the host app backend to retrieve user data.

Backend returns user data

The host app backend validates the access token and returns user data.

Platform forwards user data to miniapp

The Boxo platform forwards the user data via an HTTPS request to the mini app backend.

Miniapp backend processes user

The mini app backend registers a new user or identifies an existing one, then issues an authorization token to the Boxo platform.

Authorization token returned to SDK

The Boxo platform returns the authorization token to the Boxo native SDK.

Token passed to miniapp

The authorization token is passed to the mini app.

Miniapp requests user data

The mini app sends a request with the authorization token to the mini app backend to retrieve user data.

Backend validates and returns data

The mini app backend validates the authorization token and returns the user data.

User successfully authorized

The user is successfully authorized and can proceed within the mini app.

Setting up the backend

*Note: Feature must be enabled in Dashboard Partnership

Data formatCurrently, data exchange is conducted in JSON format. String size limits are defined within the respective data types.

Get access token

This endpoint allows the Boxo platform to obtain an access token in exchange for an authorization code.URL and METHODThis endpoint must handle a HTTPS POST request URL to endpoint must be provided in Dashboard

Headers

Key	Value
Authorization	`<prefix> <base64 encoded(hostapp_client_id:hostapp_secret_key)>`
X-Miniapp-App-ID	`<app_id - Miniapp identifier>`
X-Hostapp-Client-ID	`<client_id - Hostapp identifier>`

Default <prefix>: Token. Access token prefix can be set in Boxo Connect.
hostapp_client_id and hostapp_secret_key must be provided in Dashboard

Body

Field	Data type	Description
auth_code	String	Auth code provided by hostapp to Boxo SDK

Response

Response status must be 200 in all cases
Response body:

Field	Data type	Optional	Description
`access_token`	String(1000)	No, except `error_code` provided	Access token for get user data request. To use in payments requests enable `Use access token` in Boxo Payments.
`refresh_token`	String(1000)	Yes	Refresh token for get user data request. To use in payments requests enable `Use access token` in Boxo Payments.
`error_code`	String	Yes	If some error is occured error code should be provided. Example: `{"error_code": "INVALID_AUTH_CODE"}` All error codes can be found here

Request Example:

    curl --location --request POST '[YOUR_SERVER_URL]/api/get_access_token/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic {{BASE64_ENCODED_CLIENT_ID_AND_CLIENT_SECRET}}' \
    --data-raw '{ "auth_code": "{{HOSTAPP_AUTH_CODE_THAT_COMES_FROM_SDK}}" }'

Get user data

This endpoint allows the Boxo platform to retrieve user data using an access token.URL and METHOD

This endpoint must handle a HTTPS GET request
URL to endpoint must be provided in Dashboard

Headers

Key	Value
`Authorization`	`Token <access_token>`
`X-Miniapp-App-ID`	`<app_id - Miniapp identifier>`
`X-Hostapp-Client-ID`	`<client_id - Hostapp identifier>`

Response:

Response status must be 200 in all cases
Response body:

Field	Data type	Optional	Description
`user_data`	UserData	No, except `error_code` provided	Hostapp user data.
`error_code`	String	Yes	If some error is occured error code should be provided. Example: `{"error_code": "INVALID_ACCESS_TOKEN"}` All error codes can be found here

UserData

Field	Data type	Optional	Description
`reference`	String(100)		Reference to user in Hostapp Server
`email`	String	Yes	Verified user email address
`phone`	String	Yes	Verified user phone number in E.164 format
`first_name`	String	Yes	User’s first name
`last_name`	String	Yes	User’s last name
`custom_attributes`	JSON	Yes	Custom attributes

WARNING For Shopboxo miniapps either email or phone must be provided

Request Example:

    curl --location --request GET '[YOUR_SERVER_URL]/api/get_user_data/'\
    --header 'Content-Type: application/json' \
    --header 'Authorization: Token {{ACCESS_TOKEN}}'

Required fieldsEach 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

Setting up the SDK

InitializationParameter 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 idTo launch a specific mini app, you must first call the initialization method.

let miniapp = Boxo.shared.getMiniapp(appId: "app_id")
miniapp.delegate = self
miniapp.open(viewController: self)
...
extension ViewController : MiniappDelegate {
    func onAuth(miniapp: Miniapp) {
        //get AuthCode from hostapp backend and send it to miniapp
        miniapp.setAuthCode(authCode: "auth_code")
    }
}

val miniapp = Boxo.getMiniapp("app_id")
miniapp.setAuthListener { _, miniapp ->
    //get AuthCode from hostapp backend and send it to miniapp
    miniapp.setAuthCode("auth_code")
}
miniapp.open()

Boxo.openMiniapp('app_id');
Boxo.lifecycleHooksListener(
    onAuth: (appId) { // called when authorization flow starts
        //get AuthCode from hostapp backend and send it to miniapp
        Boxo.setAuthCode('app_id', 'auth_code');
    }
);

Boxo.openMiniapp('app_id')
Boxo.lifecycleHooksListener({
    onAuth: (appId: string) => {
        //get AuthCode from hostapp backend and send it to miniapp
        Boxo.setAuthCode('app_id', 'auth_code');
    },    
});

Boxo.openMiniapp({ appId: 'app_id'});
Boxo.addListener('miniapp_lifecycle', event => {
  if (event.lifecycle == 'onAuth') {
    //get AuthCode from hostapp backend and send it to miniapp
    Boxo.setAuthCode({ appId: 'app_id', 'auth_code'});
  }
});

Boxo.openMiniapp({ appId: 'app_id' })
Boxo.addAuthListener((authEvent) => {
    //get AuthCode from hostapp backend and send it to miniapp
    Boxo.setAuthCode('app_id', 'auth_code')
});

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 PlatformURL and METHOD

This is HTTPS GET /api/v1/accounts/consent/get_consent/ endpoint

Query Parameters:

Parameter	Data type	Description
`client_id`	String	Hostapp identifier
`app_id`	String	Miniapp identifier
`user_reference`	String	Reference to user in Hostapp Server

Response:

{
   "is_consented": <Bool>
}

This is the streamlined Direct flow where the host app backend directly sends user data to the Boxo Platform.

Direct Flow Diagram

Here is diagram showcasing the hostapp user authorization inside miniapp

Authentication and User Authorization Flow

User launches miniapp

The user opens the host app and launches the miniapp.

Miniapp identifies user needs

The miniapp determines that user identification is needed to proceed.

JS SDK login call

The miniapp calls appboxosdk.login JS SDK event to request login action.

Consent screen displayed

The user sees a consent dialog asking to “Allow miniapp to access your account information” with an “Allow” button.

Auth Gateway request

After user consent, the system makes a request to the host app’s authentication gateway.

Host app sends user data

The host app backend sends the user data to the Boxo Platform connect/ endpoint.

Platform forwards to miniapp

The Boxo Platform forwards the user data to the miniapp backend.

Miniapp generates auth token

The miniapp backend processes the user data and generates an authorization token.

Token returned to host app

The token is also provided back to the host app.

Token sent to miniapp

The authorization token is sent back through the chain to the miniapp frontend.

User authorized

The miniapp server authorizes the user using the token.

Flow completed

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 for Direct

*Note: Feature must be enabled in Dashboard Partnership

Data formatCurrently, 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

Key	Value
Content-type	`application/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

Field	Data type	Optional	Description
`client_id`	String	No	Hostapp identifier
`app_id`	String	No	Miniapp identifier
`user_data`	UserData	No	User information object

UserData

Field	Data type	Optional	Description
`reference`	String	No	Reference to user in Hostapp Server
`email`	String	Yes	Verified user email address
`phone`	String	Yes	Verified user phone number in E.164 format
`first_name`	String	Yes	User’s first name
`last_name`	String	Yes	User’s last name
`custom_attributes`	JSON	Yes	Custom attributes

Response

Response status 200 for success, 400 for errors
Response body:

Success Response (200):

Field	Data type	Description
`token`	String	Auth token
`refresh_token`	String	Refresh token

Error Response (400):

Field	Data type	Optional	Description
`error_code`	String	No	Error code
`error_message`	String	No	Detailed error message
`exception`	String	Yes	Exception details if available
`custom_attributes`	Object	Yes	Additional 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
}

email
phone
first_name
last_name
custom_attributes

Setting up the SDK for Direct

iOS
Android
Flutter
ReactNative

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>"])
    }
}

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

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>'
        });
    }
);

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>'
        });
    },    
});

This is Boxo endpoint to get status of user consent in Boxo PlatformURL and METHOD

This is HTTPS GET /api/v1/accounts/consent/get_consent/ endpoint

Query Parameters:

Parameter	Data type	Description
`client_id`	String	Hostapp identifier
`app_id`	String	Miniapp identifier
`user_reference`	String	Reference to user in Hostapp Server
Response:

{
   "is_consented": <Bool>
}

Welcome

Host Apps

Miniapps

API References

White Label Miniapps

Changelog

Introduction

​Introduction

​Query Parameters:

​Query Parameters:

Introduction

Query Parameters:

Query Parameters: