Apps

App security and best practices

Protect the install key, the portal, and calls to Blnk before users rely on your app.

An app calls Blnk with a scoped key, and Blnk checks that key on every request. You store the key, decide which domains can embed the portal, and send each call from your server. Follow these practices before users rely on the app in production.

How Blnk keeps apps safe

Blnk keeps the app off Core. The app calls Blnk, and Blnk forwards ledger calls to the instance where it is installed. Read Apps overview.

Blnk handles	You handle in your app
A scoped API key for each install	Protecting and storing the API key safely
Permission checks on every request	Securing the portal users see in the dashboard
Cancelling the install if your app does not confirm in time	Checking granted permissions before sensitive actions

Protect secrets

The install callback includes a scoped API key. Treat it like any production credential.

Encrypt before you save it. Do not store the key in plain text in your database. Use encryption or a secrets manager that fits your stack.
Keep keys on the server. Never put the scoped API key in the browser, in a portal_url, or in client-side code.
Confirm installs quickly. Return a successful response within about 10 seconds of the install callback. If your app does not confirm in time, Blnk cancels the installation and revokes the key.
Log safely. Use install IDs and key prefixes for debugging. Do not log full API keys, portal session tokens, or third-party secrets.

Install and uninstall events

Blnk sends install and uninstall events to your callback URL.

Process each event once. Use the idempotency_key Blnk sends to detect duplicates. If you already handled an event, return success again without repeating side effects.
On uninstall, stop using that install. Mark the installation inactive, remove portal sessions, and stop background jobs that used that install’s API key.

Permissions

Request only the scopes your app needs. Users can approve a subset of what you ask for.

At runtime, trust granted_permissions. That list from the install event is what the user approved. Check it before reads, writes, or alert actions even if the manifest requested more.
Your app does not inherit user access. A workspace admin installing your app does not give the app their personal permissions. The app can only do what was granted to that install.

An install can hold these scopes.

Scope	What the app can do
`data:read`	Read ledger data, such as ledgers, balances, identities, and transactions.
`data:write`	Write ledger data, such as committing a transaction or updating an identity.
`alerts:read`	Read alerts.
`alerts:write`	Create, update, and delete alerts.

Calling Blnk from your backend

Call Blnk from your server with the install’s scoped key. On Blnk Cloud the host is https://api.cloud.blnkfinance.com. On a self-hosted Enterprise deployment the host is ENTERPRISE_PUBLIC_URL.

Use the Proxy API to connect to the instance the app is installed on. Send that install’s instance_id with the Enterprise API call. The key is bound to that instance.

URLs you register in the manifest

When you register the app, the manifest includes the callback URL and, when the app has a UI, the portal URL. Blnk calls those URLs over the internet.

Production: Use public HTTPS endpoints that Blnk can reach from the internet.
Local development: Use a tunnel service, such as ngrok, and register the HTTPS URL. localhost does not work when the dashboard embeds the app.

Blnk checks those URLs when you register the app. An invalid or unreachable URL blocks registration or launch.

Portal and dashboard embedding

When the app has a UI, launch opens your portal_url inside the dashboard. Set Content-Security-Policy on the portal pages to name the domains that can embed the app. The browser allows an embed only from an origin you list.

Content Security Policy

frame-ancestors is that list. Include 'self' so a redirect on your own origin, such as /portal/enter to /portal, still loads inside the frame.

Allow the Cloud dashboard to embed the app.

Content-Security-Policy: frame-ancestors 'self' https://blnkfinance.com https://*.blnkfinance.com

Allow the dashboard at ENTERPRISE_PUBLIC_URL to embed the app. That value is the public URL of the deployment, including https://.

Content-Security-Policy: frame-ancestors 'self' ENTERPRISE_PUBLIC_URL

Portal sessions and URLs

Return a new portal_url every time someone launches the app from the dashboard.
Use short-lived portal sessions. Roughly 5 to 15 minutes is a good default. Validate the session on every portal page load and API request from the UI.
The portal_url is for your interface only. Do not put API keys, provider secrets, or other sensitive data in the link.