Skip to main content

Documentation Index

Fetch the complete documentation index at: https://guide.cloud.blnkfinance.com/llms.txt

Use this file to discover all available pages before exploring further.

This feature is in private beta. If you want access, please contact Support.
Now, that your app is installed and working well, you can launch it from the Cloud dashboard. Just like the install process, the launch process starts in Blnk Cloud. When a user clicks Launch app in Blnk Cloud:
  1. Blnk sends a POST request to your portal generator URL.
  2. Your app checks that the install exists and is active.
  3. Your app creates a short-lived portal session.
  4. Your app returns a portal_url.
  5. Blnk opens that URL inside the dashboard.
How app portals work

​
Handling the portal request

Cloud sends a payload like this to your portal_generator_url:
generate_portal.json
{
  "installed_app_id": "instapp_...",
  "app_id": "app_...",
  "organization_id": "org_...",
  "instance_id": "inst_...",
  "user_id": "user_..."
}
FieldDescription
installed_app_idThe ID for this specific app installation. Use it to find the install record.
app_idThe ID of the app being launched.
organization_idThe organization where the app is installed.
instance_idThe Cloud instance the app should work with.
user_idThe user launching the app from Cloud.
Before returning a portal URL, your app should confirm that:
  • the install exists and is active
  • the organization_id and instance_id match the install record
validateInstallForPortal.ts
async function validateInstallForPortal(
  installed_app_id: string,
  organization_id: string,
  instance_id: string
): Promise<boolean> {
  const install = await db.getInstall(installed_app_id);
  const ok =
    install != null &&
    install.status === "active" &&
    install.organization_id === organization_id &&
    install.instance_id === instance_id;

  if (!ok) {
    return false;
  }

  return true;
}

​
Create a portal session

Next, your app should create a portal session once the portal request is validated. The session helps your app know:
  • which installation opened the portal
  • which organization and instance the portal is launched from
  • which user launched the app
  • when the session should expire
createPortalSession.ts
async function createPortalSession(
  installed_app_id: string,
  organization_id: string,
  instance_id: string
): Promise<string> {
  const session = await db.createPortalSession(installed_app_id, organization_id, instance_id);
  return session.token;
}
We recommend keeping portal sessions short-lived. A 5 to 15 minute expiry is usually enough for launch sessions.
Create a portal URL
After creating the session, return a portal_url to Cloud. The response should look like this:
Expected response
{
  "portal_url": "https://app.yourcompany.com/?token=short-lived"
}
Cloud then uses this URL to open your app inside the dashboard.
The portal URL should only point to your app interface. It should not include API keys, provider secrets, or any sensitive data.

​
Load the app inside Cloud

When Cloud opens the portal_url, it loads your app inside the dashboard.
Load the app inside Cloud
To enable Cloud to successfully embed the app, you need to set the following HTTP header: 
Content-Security-Policy: frame-ancestors https://cloud.blnkfinance.com
A few rules to keep in mind during this process:
  • Blnk sends a fresh portal request for every launch. Your app should return a fresh portal_url for each request.
  • Keep Cloud API keys on the backend. Do not expose them in the browser.

​
Test the launch flow

To test app launch:
  1. Install the app in Cloud.
  2. Click Launch app from the app details page.
  3. Confirm your portal_generator_url receives the launch request.
  4. Confirm your app creates a portal session.
  5. Confirm your app returns a valid portal_url.
  6. Confirm the app opens inside the Cloud dashboard.
  7. Confirm expired sessions can no longer open the portal.
Once this works, users can open your app from Blnk Cloud and interact with the workflow inside the dashboard.

Run the example KYC app

Open the demo repository and follow its README to run the KYC example app this documentation is built around.

​
Need help?

If you’re having trouble with Blnk Cloud, don’t hesitate to send us a message via email at support@blnkfinance.com or send us a message here.