Boxo Connect is a single sign-on functionality that allows the host app user to be authorized within the miniapp. In essence, the Boxo Platform facilitates the transfer of user data from the host app backend to the miniapp backend for user authorization, after which a session token is returned to the miniapp for continued access.

Notice Our backend will make a request for creating a user and for getting an authorization token.

When creating a user, you need to generate a random password and send it to us via email. This password can be used by the user to log in to your service outside of the Boxo SDK.

​
Prerequisites

  • User authorization system

​
Boxo Connect flow

Here is diagram showcasing the hostapp user authorization inside miniapp

Here is the revised flow for better clarity:

  1. User opens host app and launches miniapp: The user opens the host app and starts the miniapp.
  2. User should be identified to proceed with the flow: This could involve product purchase, user registration, etc.
  3. appboxo.login() is called from inside the miniapp: The miniapp requests a login action via Boxo’s SDK.
  4. User is asked for confirmation to give access to personal data: The user is prompted to confirm sharing personal data necessary for the miniapp’s authorization process.
  5. Boxo’s native SDK gets the auth code generated by the host app: Boxo SDK receives the authorization code and sends an HTTPS request to the Boxo platform with the auth code.
  6. Boxo’s platform sends an HTTPS request to the host app backend: The Boxo platform sends the auth code to the host app’s backend for validation.
  7. Host app backend validates the auth code and returns an access token: The backend checks the auth code and sends back an access token.
  8. Boxo’s platform sends an HTTPS request to the host app backend to get user data: The Boxo platform requests the user data from the host app backend using the access token.
  9. Host app backend validates the access token and returns user data: The host app backend confirms the validity of the access token and sends the user data back.
  10. Boxo’s platform sends an HTTPS request with the user data to the miniapp backend: Boxo platform forwards the user data to the miniapp backend for processing.
  11. Miniapp backend either registers a new user or identifies an existing one: The miniapp backend registers the user or identifies the existing user, then sends an authorization token back to Boxo platform.
  12. Boxo platform sends back the authorization token to the Boxo native SDK: The authorization token is sent back to the Boxo SDK that initiated the request.
  13. Authorization token is passed to the miniapp: The token is provided to the miniapp.
  14. Miniapp makes a request with the token to get user data from the miniapp backend: The miniapp sends the token to its backend for user data.
  15. Miniapp backend recognizes the token and sends back user data: The miniapp backend verifies the token and returns the user data.
  16. User is authorized and continues with the miniapp flow: The user is successfully authorized and can proceed with 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 back end

Note: Feature must be enabled in Dashboard Partnership

​
Generate Auth Token

This endpoint is for the Boxo platform to send user data along with miniapp credentials and receive an authorization token in return.

URL and METHOD:

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

Headers

KeyValue
AuthorizationBasic <base64 encoded(app_id:secret_key)>
X-Hostapp-Client-IDReference to identify hostapp

Body:

Note: request body will be string if user data encrypted.

FieldData typeDescription
referenceString(100)Reference to user in Hostapp Server
emailStringVerified user email address
phoneStringVerified user phone number in E.164 format
first_nameStringUser’s first name
last_nameStringUser’s last name
custom_attributesJSONCustom attributes

Response:

  • Response status must be 200 in all cases
  • Response body:
Data typeOptionalDescription
auth_tokenStringYesAuthorization token for authenticating user in miniapp
error_codeStringYesIf some error is occured error code should be provided. Example: {"error_code": "INVALID_USER_DATA"} All error codes can be found here
phoneStringVerified user phone number in E.164 format
first_nameStringUser’s first name
last_nameStringUser’s last name
custom_attributesJSONCustom attributes

In the backend, follow these steps:

  1. For new users:

    • Create a new user account with the received inputs for new users.
    • Ensure that the new user account is identical to the regular user accounts within your authorization system.
    • Generate a random password for the user.
    • Send an email to the user with the generated password so they can log in to the service outside of the host app environment (e.g., on a Desktop or through a standalone native app).

  2. For existing users:

    • If the user already exists in your database, generate an authorization token for the user and return it.

  3. Return the access token:

    • At the end of the login process, generate an authorization token.
    • The authorization token will serve as proof that the API calls made are from a specific user.
    • You can also specify the session expiry time according to your preferences.

Example:

curl --location --request POST '[YOUR_SERVER_URL]/get_auth_token/' \
--header 'Authorization: Basic {{BASE64_ENCODED_APP_ID_AND_SECRET_KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"reference": "{{HOSTAPP_USER_REFERENCE}}",
	"email": "{{USER_EMAIL}}",
	"phone": "{{USER_PHONE}}",
	"first_name": "{{USER_FIRST_NAME}}"
	"last_name": "{{USER_LAST_NAME}}"
}'

Add Get Token URL and Required Fields to miniapp settings

On the My miniapps page, choose the miniapp, and go to settings. Enter Get Auth Token URL and Required field in the appropriate input fields.

​
Authorizing users at different phases of miniapp experience

You can authorize users at different stages based on your miniapp’s user experience. This can occur either when the miniapp is launched or during the checkout process.

When authorization is triggered, the Boxo SDK will prompt the user for permission to transfer their data from the host app to the miniapp. Once the User approves the request, the miniapp receives the access token, indicating that the user is successfully authorized.

const handleLogin = async () => {
  try {
    const {
      // token string
      token
    } = await appboxo.login()
  } catch (error) {
    console.error(error)
    // Prompt authorization failure
  }
}
Notice During successful authorization, Boxo JS SDK automatically saves a token with ab_token key to cookies.

​
Logging out

Whenever you need to logout the user, you can call the logout() function, which will clear cookies and log out the user from the miniapp.

const handleLogout = async () => {
  try {
    await appboxo.logout()
  } catch (error) {
    console.error(error)
    // Prompt logout failure
  }
}

​
Security

You can secure the connection with the following methods.

IP Filter

You can set up an IP filter to secure the connection between Boxo and your miniapp. For security purposes, you should only accept requests from Boxo’s verified IP address (157.230.199.227). This ensures that the requests are coming from Boxo’s trusted servers, adding an extra layer of protection to the communication.

Authorization Header

Boxo will send requests with a Basic Authorization header containing the app_id and secret_key provided in the Dashboard. These credentials ensure that the requests are authenticated and that only authorized applications can access the resources within the miniapp.