Building a Custom App | Blnk Cloud Guide

This feature is in private beta. If you want access, please contact Support.

This guide shows you how to build and register in Blnk Cloud. Private Custom Apps let teams securely bring their personalised workflows into Blnk Cloud, so day-to-day work can sit next to the ledger instead of living only in spreadsheets, scripts, or other tools. When your teammates are ready to turn the app on in Cloud, they do that from the Apps library.

Installing Custom Apps

Learn how to install a Custom App in your Blnk Cloud workspace.

In this guide, you’ll learn how to:

Register a private app in Blnk Cloud
Set up your app so installs and uninstalls work correctly in Cloud
Connect your app to the selected Cloud instance
Open your app inside the Cloud dashboard

Register a private Custom App

To register your private Custom App:

Add a new private app

In the Blnk Cloud dashboard, open Apps from the side navigation (bottom left).
Click New private app on the right side of the Apps page.

This opens the manifest form, where you’ll enter the app details in the next step.

Upload your app manifest

The manifest tells Blnk Cloud how to display, install, and launch your app. Fill in the manifest form with the details below.

Field	Description
Display name	The name users will see in the Apps library.
Description	A short explanation of what your app does.
Logo URL	A public URL for your app logo.
Developer name	The company, team, or person that built the app.
Registration callback URL	The `https` endpoint Blnk calls when the app is installed or uninstalled. Learn more
Portal generator URL	The endpoint Blnk calls to create a short-lived URL for opening the app inside Cloud. Learn more
Permissions	The scopes your app needs to work. Learn more

Submit to your workspace

Submit the manifest, and you’re done! The app will be added to your organization’s Apps library.Only team members in your workspace can see and install it on whichever Cloud instances they use there.

Set up install and uninstall events

App installs always start in Blnk Cloud, not in your app. Here’s how it works:

The user opens your app in Blnk Cloud and clicks Install.
The user reviews and approves the permissions your app requested.
Blnk creates a scoped API key, api_key, for that installation based on the permissions the user approved.
Blnk sends the install payload to your registration_callback_url provided in your manifest as a POST request.
Your app stores the installation details and returns a 2xx response within 10 seconds.
If the request succeeds, the app is installed and ready to use.
The user can now launch the app from the app details page by clicking Launch app from the app details page.

Note: If your app does not return a 2xx response within 10 seconds, Blnk cancels the installation, revokes the API key, and the install fails.

The install payload structure looks like this:

Install payload

{
  "installed_app_id": "instapp_...",
  "app_id": "app_...",
  "organization_id": "org_...",
  "instance_id": "inst_...",
  "api_key": "blnk_...",
  "api_key_prefix": "blnk_abc",
  "granted_permissions": ["data:read", "alerts:read"],
  "idempotency_key": "install:instapp_..."
}

Field	Description
`installed_app_id`	The ID for this specific app installation. Use this to track the app in your system.
`app_id`	The ID of the app that was installed.
`organization_id`	The organization where the app was installed.
`instance_id`	The Cloud instance where the app was installed.
`api_key`	The scoped API key your app should use to access the selected instance. Store it securely.
`api_key_prefix`	A short, safe prefix you can use to identify the API key in logs or support flows.
`granted_permissions`	The permissions the user approved during installation. Only use these permissions.
`idempotency_key`	A unique key for this install event. Use it to avoid processing the same event twice.

What to do on install

When your app receives an install event, you should:

Store the api_key securely in your system.
Store it against the installed_app_id, or against the organization_id and instance_id.
Save the granted_permissions and only use the permissions the user approved.
Treat idempotency_key as a deduplication key. If you receive the same key twice, acknowledge it and do not create duplicate records.
Return a 2xx response quickly, then run any slower setup work in the background.

Important note: The API key is shown once and cannot be retrieved again. If it is lost, the user must uninstall and reinstall the app.

Supported permissions

Permissions define what your app can access or change in the selected Cloud instance. Your app can request any combination of these scopes:

Scope	What it allows
`data:read`	Read transactions, ledgers, identities, and balances.
`data:write`	Create and update ledger data.
`alerts:read`	Read alert configurations and events.
`alerts:write`	Create and update alert configurations.

Remember: Users can update the permissions granted during installation. Always read granted_permissions from the install payload and only use what was granted.

How uninstall works

When a user uninstalls your app, Blnk sends an uninstall payload to the same registration_callback_url.

Uninstall payload

{
  "installed_app_id": "instapp_...",
  "app_id": "app_...",
  "organization_id": "org_...",
  "instance_id": "inst_...",
  "uninstalled_at": "2026-04-21T12:00:00Z",
  "idempotency_key": "uninstall:instapp_..."
}

When your app receives an uninstall event, you should:

Delete or invalidate the stored api_key for the installed_app_id.
Mark the app as uninstalled in your own system.
Use idempotency_key to avoid processing the same uninstall twice.
Return a 2xx response.

Important note: If your endpoint returns an error on uninstall, Blnk aborts the uninstall. That prevents a broken state where the app looks disconnected in Cloud while your backend still holds a live key.

Handling install and uninstall events

Since your registration_callback_url handles both events, use the idempotency_key to tell them apart.

Install events start with install:
Uninstall events start with uninstall:

Sample event handler

app.post("/blnk/hooks", async (req, res) => {
  const idempotencyKey = req.body.idempotency_key;
  const body = req.body;

  if (idempotencyKey.startsWith("install:")) {
    await store.saveInstall({
      installedAppId: body.installed_app_id,
      organizationId: body.organization_id,
      instanceId: body.instance_id,
      apiKey: body.api_key,
      permissions: body.granted_permissions,
    });

    return res.status(200).json({ ok: true });
  }

  if (idempotencyKey.startsWith("uninstall:")) {
    await store.markUninstalled(body.installed_app_id);

    return res.status(200).json({ ok: true });
  }

  return res.status(400).json({ error: "unknown event" });
});

Connect your app to the selected instance

After your app is installed, Blnk sends two important values in the install payload: api_key and instance_id. You’ll need both values when your app makes requests to Blnk.

Understand the request URL

All requests start with the same base URL:

https://api.cloud.blnkfinance.com

After the base URL, choose the API path based on what your app wants to do:

Use this path	When to use it	URL format
`/proxy`	When your app needs to call a Blnk Core endpoint through Cloud.	`/proxy/<core-endpoint>?instance_id=<instance_id>`
`/data`	When your app needs to read or filter ledger data through Cloud.	`/data/<resource>?instance_id=<instance_id>`
`/`	Call a Blnk Cloud endpoint directly.	e.g. `/alerts`

The api_key goes in the request header:

Authorization: Bearer <api_key>

The instance_id goes in the URL so that the request gets routed to the connected Core instance:

?instance_id=<instance_id>

Quick reference:

Use /proxy when you want Cloud to forward a request to Core.
Use /data when you want to directly query and filter ledger data.
Use /<endpoint> when you want to call a Blnk Cloud endpoint directly, e.g. alerts.

In all cases, include the installed app’s API key in the Authorization header.

1. Use `/proxy` to call Core endpoints through Cloud

Use the proxy when your app wants to call Blnk Core through Cloud. The format is:

https://api.cloud.blnkfinance.com/proxy/<core-endpoint>?instance_id=<instance_id>

The <core-endpoint> is the same endpoint you would normally call on Core, but with /proxy in front of it. For example, on Core, the request would look like this:

GET /ledgers

With the Cloud Proxy, it becomes:

GET https://api.cloud.blnkfinance.com/proxy/ledgers?instance_id=inst_...

A complete request via the Cloud Proxy would look like:

bash

curl -X GET "https://api.cloud.blnkfinance.com/proxy/ledgers?instance_id=inst_..." \
  -H "Authorization: Bearer blnk_..." \
  -H "Content-Type: application/json"

Using the proxy

Learn more about how the proxy works and see all the available endpoints.

2. Use `/data` to read data from the selected instance

Use /data when your app needs to read or filter ledger data through Cloud. The format is:

https://api.cloud.blnkfinance.com/data/<resource>?instance_id=<instance_id>

For example, to read transactions:

curl -X GET "https://api.cloud.blnkfinance.com/data/transactions?instance_id=inst_..." \
  -H "Authorization: Bearer blnk_..." \
  -H "Content-Type: application/json"

You can also add filters to the query string:

curl -X GET "https://api.cloud.blnkfinance.com/data/transactions?instance_id=inst_...&status_eq=APPLIED&currency_eq=USD" \
  -H "Authorization: Bearer blnk_..." \
  -H "Content-Type: application/json"

Using the data API

Learn more about how the data API works and see all the available operations.

3. Call Cloud endpoints directly

Some Cloud APIs are direct endpoints. They are not called through /proxy or /data. For example, to create or manage alerts, call the Alerts API directly:

https://api.cloud.blnkfinance.com/alerts/flag/<resource_id>

Load your app inside Cloud

When a user launches your app from Blnk Cloud, Cloud needs a URL it can open inside the dashboard. Here’s how it works:

The user clicks Launch app in Blnk Cloud.
Blnk sends a POST request to your portal_generator_url provided in your manifest.
Your app checks the request and creates a short-lived portal session.
Your app returns a portal_url.
Blnk opens that URL inside the Cloud dashboard.

Portal request payload

{
  "installed_app_id": "instapp_...",
  "app_id": "app_...",
  "organization_id": "org_...",
  "instance_id": "inst_...",
  "user_id": "user_..."
}

Field	Description
`installed_app_id`	The ID for this specific app installation. Use it to find the stored install record for the app.
`app_id`	The ID of the app being launched.
`organization_id`	The organization where the app is installed.
`instance_id`	The Cloud instance the app should work with.
`user_id`	The user launching the app from Cloud.

Your app should return a 2xx response within 10 seconds with a portal_url.

Expected response

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

Portal URL requirements

Make sure to set your frame policy so Blnk Cloud can embed the app: The portal_url should be:

Short-lived: Generate a fresh URL each time the app is launched. A token lifetime of 5 to 30 minutes is usually enough.
Embeddable: Set your frame policy so Blnk Cloud can embed the app:
Required HTTP Header
```
Content-Security-Policy: frame-ancestors https://cloud.blnkfinance.com
```
Access-controlled: Treat the URL as sensitive until the token expires.

What to do on portal request

When your app receives a portal request, you should:

Use installed_app_id to find the install record you saved during installation.
That record should include the app’s stored api_key, instance_id, and granted_permissions.
Use those values to decide what the user can see or do inside the app portal.

Test your flow

Before publishing your app, test the flow to make sure it works as expected:

Register the app

Confirm that your manifest details are correct, especially:

registration_callback_url
portal_generator_url
requested permissions

Install the app

Install the app from the Apps library and confirm that your registration_callback_url receives the install payload.Check that your app stores:

installed_app_id
organization_id
instance_id
api_key encrypted at rest
granted_permissions

Make a test API call

Use the stored api_key and instance_id to make a simple request through Cloud.For example, create a new ledger on the selected instance. Verify that the request is successful and that the ledger is created.

Launch the app

Click Launch app in Cloud and confirm that:

Blnk sends a request to your portal_generator_url
your app returns a valid portal_url
the app loads correctly inside the Cloud dashboard

Uninstall the app

Uninstall the app and confirm that your app receives the uninstall payload.Your app should revoke or delete the stored API key and mark the installation as uninstalled.

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.

Start Here

Instances

Insights

Ledgers

Balances

Transactions

Identities

Reconciliation

Filters & Views

Alerts

Custom Apps

Settings

Integrations

Documentation Index

Installing Custom Apps

​Register a private Custom App

Add a new private app

Upload your app manifest

Submit to your workspace

​Set up install and uninstall events

​What to do on install

​Supported permissions

​How uninstall works

​Handling install and uninstall events

​Connect your app to the selected instance

​Understand the request URL

​1. Use /proxy to call Core endpoints through Cloud

Using the proxy

​2. Use /data to read data from the selected instance

Using the data API

​3. Call Cloud endpoints directly

​Load your app inside Cloud

​Portal URL requirements

​What to do on portal request

​Test your flow

Register the app

Install the app

Make a test API call

Launch the app

Uninstall the app

​Need help?

Register a private Custom App

Set up install and uninstall events

What to do on install

Supported permissions

How uninstall works

Handling install and uninstall events

Connect your app to the selected instance

Understand the request URL

1. Use `/proxy` to call Core endpoints through Cloud

2. Use `/data` to read data from the selected instance

3. Call Cloud endpoints directly

Load your app inside Cloud

Portal URL requirements

What to do on portal request

Test your flow

Need help?