Apps

Install app

Install a registered app on a Cloud instance.

POST/apps/{slug}/install

Install a registered app on one Cloud instance. Blnk creates a scoped API key, sends the install to the app’s registration callback, and finishes the install when that callback returns 2xx.

An admin or a member calls this with a user session token, the account password, and two_factor_code when 2FA is on. An API key cannot install an app.

Authorizationstringrequiredheader

Bearer session token for the current organization.

Path

slugstringrequiredpath

slug from Register app.

Query

instance_idstringquery

Core instance to install the app on (instance_...). Send this when the body does not include instance_id.

Body

instance_idstringrequiredbody

Core instance to install the app on (instance_...). The instance has to belong to the current organization, and the app can be installed once on it. You can send this as a query parameter instead.

passwordstringrequiredbody

Account password of the signed-in user.

two_factor_codestringbody

2FA code. Required when 2FA is on for this user.

permissionsstring[]body

Scopes to grant on this install. Omit it to grant every permission the app declares. If the app declared none, Blnk grants data:read.

A list you send has to be a non-empty subset of those permissions.

Response

A 201 response returns the installation and the API key. Save installed_app_id and api_key.

installed_app_idstringrequired

Id of this installation (instapp_...). Use it on Launch app.

app_idstringrequired

Id of the app (app_...).

api_keystringrequired

Scoped API key for this installation (blnk_...). The app uses it to call Blnk for this instance.

api_key_prefixstringrequired

Prefix of api_key, safe to store in logs.

granted_permissionsstring[]required

Scopes granted on the key.

pinnedbooleanrequired

Whether the app is pinned in the sidebar. false on a new install.

messagestringrequired

App installed successfully.

curl -X POST "https://api.cloud.blnkfinance.com/apps/stripe-sync/install" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "instance_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "password": "account-password",
    "permissions": ["data:read"]
  }'

{
  "installed_app_id": "instapp_8cc22560-5ace-4989-8953-fcbad7947d48",
  "app_id": "app_049495fe-6f03-4e7b-b3b4-7b0466c127c7",
  "api_key": "blnk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "api_key_prefix": "blnk_01234567",
  "granted_permissions": ["data:read"],
  "pinned": false,
  "message": "App installed successfully."
}

{
  "error": "app installation requires a user session token"
}

{
  "error": "password is required to install an app"
}

{
  "error": "two_factor_code is required"
}

{
  "error": "password verification failed"
}

{
  "error": "2fa verification failed"
}

{
  "error": "instance_id is required (body or query)"
}

{
  "error": "app is already installed for this instance"
}

{
  "error": "instance does not belong to this organization"
}

{
  "error": "registration handshake failed: registration callback returned status 500"
}

{
  "error": "permission \"alerts:write\" is not among the permissions this app requests"
}

{
  "error": "App not found"
}

{
  "error": "Organization not found"
}

{
  "error": "User not authenticated"
}

Install app

Header

Path

Query

Body

Response