Create an application

POST /v1/apps

Registers an OAuth application in your Bitrix24 account and creates a paired API key. Send a flat request body without a wrapper.

Request fields (body)

handlerUrl is set by the platform — it is not accepted in the body. OAuth callbacks and opening a placement go through it. For the difference between appUrl and handlerUrl, see the Applications section.

Examples

The JavaScript examples run in Node.js on Linux/macOS. They save the one-time key to an app.key file in a separate private directory inside the home directory and print only the file path and application id. Move the key to your secret store.

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/apps \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales dashboard",
    "scopes": ["crm", "user", "placement"],
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com"
  }'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/apps \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales dashboard",
    "scopes": ["crm", "user", "placement"],
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com"
  }'

JavaScript — personal key

import { mkdtemp, writeFile } from 'node:fs/promises'
import { homedir } from 'node:os'
import { join } from 'node:path'

const keyDir = await mkdtemp(join(homedir(), '.vibecode-app-'))
const res = await fetch('https://vibecode.bitrix24.com/v1/apps', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Sales dashboard',
    scopes: ['crm', 'user', 'placement'],
    appUrl: 'https://app-abc12345.vibecode.bitrix24.com',
  }),
})

const { data } = await res.json()
// The key is returned only once; only the owner can read the file
const keyPath = join(keyDir, 'app.key')
await writeFile(keyPath, data.rawKey, { mode: 0o600, flag: 'wx' })
console.log('App ID:', data.id)
console.log('Key file:', keyPath)

JavaScript — OAuth application

import { mkdtemp, writeFile } from 'node:fs/promises'
import { homedir } from 'node:os'
import { join } from 'node:path'

const keyDir = await mkdtemp(join(homedir(), '.vibecode-app-'))
const res = await fetch('https://vibecode.bitrix24.com/v1/apps', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Sales dashboard',
    scopes: ['crm', 'user', 'placement'],
    appUrl: 'https://app-abc12345.vibecode.bitrix24.com',
  }),
})

const { data } = await res.json()
// The key is returned only once; only the owner can read the file
const keyPath = join(keyDir, 'app.key')
await writeFile(keyPath, data.rawKey, { mode: 0o600, flag: 'wx' })
console.log('App ID:', data.id)
console.log('Key file:', keyPath)

Response fields

Response example

rawKey is shown with a truncated secret — this is not a working value.

{
  "success": true,
  "data": {
    "id": "33c4d5e6-f7a8-49b0-1234-5c6d7e8f9012",
    "title": "Sales dashboard",
    "description": null,
    "scopes": ["crm", "user", "placement"],
    "handlerUrl": "https://vibecode.bitrix24.com/v1/bitrix-handler",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.com",
    "redirectUris": [
      "https://vibecode.bitrix24.com/oauth/complete",
      "http://localhost"
    ],
    "bitrixClientId": "local.7c3d4e5f6a7b80.55556666",
    "authorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "authorBitrixUserId": 42,
    "authorBitrixUserIdSource": "member",
    "portalId": "8b1f0e2a-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "createdAt": "2026-06-24T09:12:45.781Z",
    "updatedAt": "2026-06-24T09:12:45.781Z",
    "placements": [],
    "catalogStatus": "PRIVATE",
    "publishedAt": null,
    "placementResizeEnabled": false,
    "mobile": false,
    "hosting": "platform",
    "externalHost": null,
    "externalRegistrable": null,
    "rawKey": "vibe_app_local_7c3d4e5f6a7b80_55556666_…_6666"
  }
}

Error response example

400 — validation failed:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "title: Required"
  }
}

Errors

The full list of general API errors — Errors.

Known specifics

• The platform reports non-ASCII characters lost from the title. A value sent without explicit UTF-8 serialization arrives with question marks instead of letters: the bytes are lost on the client side, before the request is sent. Windows PowerShell sends values this way. The application is still created as is, and the response carries warnings naming the field — the title becomes the Bitrix24 catalog card name on publish, so fix it right away. A ready-to-run call with UTF8.GetBytes — Windows / PowerShell and UTF-8.
• A pair is created: an application and an API key. Registration creates an application record and a paired authorization key in one step. This affects deletion: the key frees a slot in the per-user limit only after deleting the application.
• Application scopes and paired-key scopes are different sets. In scopes you declare access to Bitrix24 account data — crm, user, placement. If the calling key's rights set is not fixed, the paired key receives that set plus platform scopes: vibe:infra — servers and agents, vibe:ai — model calls, vibe:search — web search and research, vibe:storage — object storage (only when the calling key has PERSONAL origin). The authorization key can then create servers through POST /v1/infra/servers right away, even though vibe:infra was never in the create body. The data.scopes field of the response shows the application declaration, not the key's effective set — read the effective set from data.scopes of GET /v1/me called with that key.
• A key with a fixed rights set grants the paired key exactly what was declared. The rights set is fixed for a partner key, for a Cowork project key, for a personal key issued by the Vibecode dashboard form and for a key issued with exactScopes: true — Management keys. An application created with such a key gets a paired key holding exactly what is listed in scopes — no platform scopes are added to it. If you need infrastructure, list vibe:infra in scopes at creation time, otherwise POST /v1/infra/servers answers 403 INFRA_SCOPE_REQUIRED. The same goes for vibe:ai, vibe:search and vibe:storage. You can only declare a right that the calling key itself holds, otherwise the answer is 403 SCOPE_GRANT_REQUIRES_CONSENT. Adding the right later through updating the application does not work: vibe:* propagation never reaches a key with a fixed set.
• Storage requires a personal key origin. If the caller key was issued to an application or has unknown origin, vibe:storage is omitted from paired-key defaults. An explicit vibe:storage in scopes returns 403 KEY_STORAGE_SCOPE_REQUIRES_PERSONAL_KEY, even if the caller already holds it. Create a new personal key with storage access.
• You can identify a key with a fixed rights set before creating the application. Call GET /v1/me with the key you plan to create the application with. The set is fixed when data.scopes matches what was ticked when the key was issued. Other keys carry vibe:ai and vibe:search in the set even when those were not ticked.
• The application opens in the account interface. Registration tells the Bitrix24 account that the application has an interface, so after creation it appears in the account menu, and with mobile: true in the mobile client as well. The mode is set at creation time and updating the application does not change it. An application that never appeared in the menu is registered as API-only: turn the API-only mode off in the application card on the Bitrix24 account, or create the application again.
• The mobile flag can only be set at creation. PATCH /v1/apps/:id does not accept mobile — a sent value is ignored, see Update an application. For an existing application, turn the flag on in the application card on the Bitrix24 account, or create the application again.

See also

• Applications
• Update an application
• Delete an application
• Publish
• Scopes
• Keys and authorization
• Rights to create keys and apps