Skip to main content

​
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.
Here is diagram showcasing the hostapp user authorization inside miniappAuthDiagramAuthentication and User Authorization Flow
1

User launches miniapp

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

User identification required

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

Miniapp calls login

The mini app calls Boxo.login().
4

User consent

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

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.
6

Platform forwards auth code

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

Backend validates and returns access token

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

Platform requests user data

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

Backend returns user data

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

Platform forwards user data to miniapp

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

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.
12

Authorization token returned to SDK

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

Token passed to miniapp

The authorization token is passed to the mini app.
14

Miniapp requests user data

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

Backend validates and returns data

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

User successfully authorized

The user is successfully authorized and can proceed within the mini app.
*Note: Feature must be enabled in Dashboard PartnershipAuthDiagramData formatCurrently, data exchange is conducted in JSON format. String size limits are defined within the respective data types.
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 DashboardAuthDiagramHeaders
KeyValue
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
FieldData typeDescription
auth_codeStringAuth code provided by hostapp to Boxo SDK
Response
  • Response status must be 200 in all cases
  • Response body:
FieldData typeOptionalDescription
access_tokenString(1000)No, except error_code providedAccess token for get user data request. To use in payments requests enable Use access token in Boxo Payments.
refresh_tokenString(1000)YesRefresh token for get user data request. To use in payments requests enable Use access token in Boxo Payments.
error_codeStringYesIf 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 '{ "authCode": "{{HOSTAPP_AUTH_CODE_THAT_COMES_FROM_SDK}}" }'
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 AuthDiagram
Headers
KeyValue
AuthorizationToken <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:
FieldData typeOptionalDescription
user_dataUserDataNo, except error_code providedHostapp user data.
error_codeStringYesIf some error is occured error code should be provided. Example: {"error_code": "INVALID_ACCESS_TOKEN"} All error codes can be found here
UserData
FieldData typeOptionalDescription
referenceString(100)Reference 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
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
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.
  • 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) {
        miniapp.setAuthCode(authCode: "[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.