Apps

Register app

POST/apps

A Custom App has to be registered before anyone can install it. This call adds the app to the current organization’s Apps library and returns the slug you use to install it.

Send is_private as true. An admin or a member can call this.

Enterprise authentication

Send these requests to https://api.cloud.blnkfinance.com on Blnk Cloud. On a self-hosted Enterprise deployment, send them to ENTERPRISE_PUBLIC_URL.

Pass an Enterprise API key, or an OAuth access token, in the X-blnk-key header. Create the key in Enterprise API keys, or issue a token with OAuth.

This credential comes from the Cloud or Enterprise workspace. A Core API key belongs to the Core instance.

X-blnk-keystringrequiredheader

Enterprise API key, or an OAuth access token.

Body

namestringrequiredbody

Name shown in the Apps library. Blnk builds slug from this name.

is_privatebooleanrequiredbody

Send true so the app stays in the current organization.

registration_callback_urlstringrequiredbody

Absolute http or https URL Blnk calls on install and uninstall. It cannot include credentials, and it cannot target localhost or a private address. See Set Up Install and Uninstall Events.

descriptionstringbody

Short explanation of what the app does.

logo_urlstringbody

Public URL of the app logo.

developer_namestringbody

Company, team, or person that built the app.

portal_generator_urlstringbody

Absolute http or https URL Blnk calls to open the app. Same address rules as registration_callback_url. Required before anyone can launch the app.

permissionsstring[]body

Scopes the app can be granted: data:read, data:write, alerts:read, and alerts:write. Omit this and an install grants data:read.

assigned_tostring[]body

User ids allowed to launch the app, from List team members. Omit it, or send an empty array, and every member can launch it. Each id has to be an active member of this organization, with a first and last name, and this field is only for a private app.

require_password_to_launchbooleanbody

When true, every launch asks for the account password again, and for two_factor_code when 2FA is on.

Response

A 201 response returns the app. Save slug.

app_idstringrequired

Id of the app (app_...).

slugstringrequired

Identifier built from name. Use it on Install app.

namestringrequired

Name shown in the Apps library.

descriptionstring

Short explanation of what the app does.

logo_urlstring

Public URL of the app logo.

developer_namestring

Company, team, or person that built the app.

registration_callback_urlstringrequired

URL Blnk calls on install and uninstall.

portal_generator_urlstring

URL Blnk calls to open the app.

permissionsstring[]

Scopes the app can be granted.

is_privatebooleanrequired

true when the app belongs to the current organization.

organization_idstring

Organization that owns the app. Set when is_private is true.

assigned_tostring[]

User ids allowed to launch the app. Empty means every member.

require_password_to_launchbooleanrequired

Whether a launch asks for the account password again.

created_atstringrequired

When the app was registered.

updated_atstringrequired

When the app was last updated.

curl -X POST "https://api.cloud.blnkfinance.com/apps" \
  -H "X-blnk-key: CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Sync",
    "is_private": true,
    "description": "Sync Stripe payments into the ledger.",
    "developer_name": "Example",
    "logo_url": "https://app.example.com/logo.png",
    "registration_callback_url": "https://app.example.com/api/callback",
    "portal_generator_url": "https://app.example.com/api/portal",
    "permissions": ["data:read", "data:write"]
  }'

{
  "app_id": "app_049495fe-6f03-4e7b-b3b4-7b0466c127c7",
  "slug": "stripe-sync",
  "name": "Stripe Sync",
  "description": "Sync Stripe payments into the ledger.",
  "logo_url": "https://app.example.com/logo.png",
  "developer_name": "Example",
  "registration_callback_url": "https://app.example.com/api/callback",
  "portal_generator_url": "https://app.example.com/api/portal",
  "permissions": ["data:read", "data:write"],
  "is_private": true,
  "organization_id": "org_01K4EX0C3A9F2B7D6E1C8A5F40",
  "assigned_to": [],
  "require_password_to_launch": false,
  "created_at": "2026-04-21T12:00:00Z",
  "updated_at": "2026-04-21T12:00:00Z"
}

{
  "error": "invalid app permission \"billing:read\" (allowed: data:read, data:write, alerts:read, alerts:write)"
}

{
  "error": "registration_callback_url must be an absolute http or https URL"
}

{
  "error": "assigned_to is only allowed for private apps"
}

{
  "error": "Organization not found"
}