Launching Your App

1. If the app requires it, the user confirms with their account password and 2FA code (same rules as install).
2. Blnk sends a POST request to your portal generator URL.
3. Your app checks that the install exists and is active.
4. Your app creates a short-lived portal session.
5. Your app returns a portal_url.
6. Blnk opens that URL inside the dashboard.

​

Handling the portal request

{
  "installed_app_id": "instapp_...",
  "app_id": "app_...",
  "instance_id": "inst_..."
}

• the install exists and is active
• the instance_id in the request matches the install record

async function validateInstallForPortal(
  installed_app_id: string,
  app_id: string,
  instance_id: string,
): Promise<boolean> {
  const install = await db.getInstall(installed_app_id);
  const ok =
    install != null &&
    install.status === "active" &&
    install.app_id === app_id &&
    install.instance_id === instance_id;

  if (!ok) {
    return false;
  }

  return true;
}

​

Create a portal session

• which installation opened the portal
• which Cloud instance the portal is launched from
• when the session should expire

import { randomBytes } from "node:crypto";
import { RelatedTopics } from "/snippets/related-topics.jsx";

const PORTAL_BASE = "https://app.yourcompany.com";
const TTL_SECONDS = 900; // 900 seconds = 15 minutes

async function createPortalSession(
  installed_app_id: string,
  instance_id: string,
): Promise<string> {
  const ttlSeconds = TTL_SECONDS;
  const expiry_time_ms = Date.now() + (ttlSeconds * 1000);
  const token = randomBytes(32).toString("base64url");
  await db.savePortalSession({
    token,
    installed_app_id,
    instance_id,
    expiry_time_ms,
  });
  const portalUrl = new URL(PORTAL_BASE);

  portalUrl.searchParams.set("token", token);

  return portalUrl.toString();
}

async function verifyPortalSession(token: string) {
  const session = await db.getPortalSession(token);

  if (!session) {
    return { ok: false as const, status: 401 };
  }

  if (session.expiry_time_ms < Date.now()) {
    return { ok: false as const, status: 410 };
  }
  
  return { ok: true as const, session };
}

{
  "portal_url": "https://app.yourcompany.com/?token=short-lived"
}

​

Load the app inside Cloud

• 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

1. Install the app in Cloud.
2. Click Launch app from the app details page.
3. If the app requires re-authentication, confirm with your password and 2FA code.
4. Confirm your portal_generator_url receives the launch request.
5. Confirm your app creates a portal session.
6. Confirm your app returns a valid portal_url.
7. Confirm the app opens inside the Cloud dashboard.
8. Confirm expired sessions can no longer open the portal.

​

Troubleshooting