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.
Boxo Connect flow
Here is diagram showcasing the hostapp user authorization inside miniapp
Authentication and User Authorization Flow
- The user opens the host app and launches the mini app.
- To proceed, the user must be identified (e.g., for product purchases or user registration).
- The mini app calls
appboxo.login()
. - The user is prompted to confirm access to their personal data required for authorization.
- The Boxo native SDK retrieves an authorization code from the host app and sends an HTTPS request to the Boxo platform.
- The Boxo platform forwards the authorization code via an HTTPS request to the host app backend.
- The host app backend validates the authorization code and returns an access token.
- The Boxo platform sends an HTTPS request with the access token to the host app backend to retrieve user data.
- The host app backend validates the access token and returns user data.
- The Boxo platform forwards the user data via an HTTPS request to the mini app backend.
- The mini app backend registers a new user or identifies an existing one, then issues an authorization token to the Boxo platform.
- The Boxo platform returns the authorization token to the Boxo native SDK.
- The authorization token is passed to the mini app.
- The mini app sends a request with the authorization token to the mini app backend to retrieve user data.
- The mini app backend validates the authorization token and returns the user data.
- 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 format
Currently, 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 METHOD
This 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> |
- Default
<prefix>
: Token. Access token prefix can be set in Boxo Connect. hostapp_client_id
andhostapp_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) | Yes | Access 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:
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> |
Response:
- Response status must be
200
in all cases - Response body:
Field | Data type | Optional | Description |
---|---|---|---|
user_data | UserData / EcryptedString | Yes | Hostapp user data, that could be sent as encrypted string. Refer to Security measures for more details |
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 |
email
or phone
must be provided Request Example:
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 (required)
- phone_number (required)
- first_name
- last_name
- shipping_address
- billing_address
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
Android
Flutter
Kotlin:
ReactNative
Kotlin:
Appboxo.logout()
for Android or Appboxo.shared.logout()
for IOS so that the miniapps’ storage is also cleared to log out the miniapp users as well. Get user consent
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:
Parameter | Data type | Optional | Description |
---|---|---|---|
client_id | String | Hostapp identifier | |
app_id | String | Miniapp identifier | |
user_reference | String | Reference to user in Hostapp Server | |
Response: |