Best Practices

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.

​

Installation lifecycle

1. Use the install payload as your source of truth When your app is installed, save the values from the install payload. At minimum, store:
   • installed_app_id
   • app_id
   • organization_id
   • instance_id
   • api_key
   • granted_permissions
   Use these values to identify the installation, route requests to the right instance, and decide what the app can access.
2. Handle retries safely Blnk may send the same install or uninstall event more than once. Use the idempotency_key to make sure your app does not create duplicate records or process the same uninstall twice. For example, if an install event arrives again with the same idempotency key, acknowledge it and return success without creating a second install record.
3. Clean up on uninstall When your app receives an uninstall event, delete or invalidate the stored API key for that installation. You should also mark the installation as uninstalled in your own system so the app no longer makes requests for that instance.

​

Security and permissions

1. Request the minimum permissions needed Only request the scopes your app actually needs. If the app only reads ledger data, request data:read instead of broader write permissions. Users can also reduce permissions during installation, so your app should not assume it received every scope it requested. Always read granted_permissions from the install payload and use it to control what the app can do.
2. Store API keys securely The install payload includes an api_key for the selected app installation. Store it securely and never expose it in the browser, logs, portal URLs, or client-side code. Treat the key like any other production secret. If the key is lost, the user must uninstall and reinstall the app to generate a new one.
3. Prefer Cloud APIs over direct Core access Apps can call a customer’s Core instance directly if they have access, but this bypasses Cloud-level controls. For installed apps, use the Cloud Proxy, Data API, and direct Cloud endpoints where possible. This keeps requests inside Cloud’s permission model and gives the app access to Cloud-managed security, rate limiting, audit logs, and workspace controls.

​

App launch and portal sessions

1. Generate a fresh portal URL for every launch When a user launches your app, Blnk calls your portal_generator_url. Your app should return a fresh portal_url for that session. Do not return a permanent app URL. Use a short-lived token so the portal link expires after a few minutes.
2. Keep portal URLs access-controlled Treat portal URLs as sensitive until they expire. A user with access to the URL may be able to open the app session while the token is valid. Your app should validate the token, confirm the installation is still active, and check that the user is allowed to access the app.
3. Make the app embeddable in Cloud The portal URL loads inside the Blnk Cloud dashboard. Configure your app so Cloud is allowed to embed it.
   Content-Security-Policy: frame-ancestors https://cloud.blnkfinance.com
   

​

Reliability and user experience

1. Return quickly from callback endpoints Install, uninstall, and portal generation endpoints should return within 10 seconds. Do only the required work before responding. For slower jobs, return a successful response first, then continue the work in the background.
2. Show clear error states If something goes wrong, show users what happened and what they can do next. Common cases include:
   • The app is missing a required permission.
   • The selected instance is unavailable.
   • The app was uninstalled.
   • The portal session expired.
   • The app cannot reach an external provider.
   Avoid generic errors like “Something went wrong” when the app can provide a clearer reason.
3. Design for one organization and instance at a time Apps are installed into a specific organization and instance. Do not assume the app has access to every instance in the workspace. Always use the organization_id and instance_id from the install payload or portal request to scope what the app shows and does.

​

Design and layout

1. Keep the app readable inside Cloud Your app does not have to match Blnk Cloud’s exact visual style. It can use its own brand or product interface. When designing the app, make sure it feels comfortable inside the Cloud dashboard:
   • Use clear spacing and readable text.
   • Avoid layouts that feel cramped inside an embedded view.
   • Make buttons, forms, and error states easy to understand.
   • Keep important actions visible without requiring too much scrolling.
   If your team wants the app to feel closer to Cloud, follow the same general principles: simple layouts, clear contrast, rounded surfaces, and calm interface colors.

​

Need help?