Создать приложение

POST /v1/apps

Регистрирует OAuth-приложение на портале Битрикс24 и создаёт парный API-ключ. Тело передаётся плоско, без обёртки.

Поля запроса (body)

handlerUrl задаёт платформа — в теле он не принимается, через него идут обратные вызовы OAuth и открытие места встраивания. Разница между appUrl и handlerUrl — в разделе Приложения.

Примеры

Примеры JavaScript предназначены для Node.js на Linux/macOS. Они сохраняют одноразовый ключ в файле app.key в отдельной закрытой папке внутри домашнего каталога и выводят только путь к файлу и идентификатор приложения. Перенесите ключ в своё хранилище секретов.

curl — личный ключ

curl -X POST https://vibecode.bitrix24.tech/v1/apps \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Дашборд продаж",
    "scopes": ["crm", "user", "placement"],
    "appUrl": "https://app-abc12345.vibecode.bitrix24.tech"
  }'

curl — OAuth-приложение

curl -X POST https://vibecode.bitrix24.tech/v1/apps \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Дашборд продаж",
    "scopes": ["crm", "user", "placement"],
    "appUrl": "https://app-abc12345.vibecode.bitrix24.tech"
  }'

JavaScript — личный ключ

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.tech/v1/apps', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Дашборд продаж',
    scopes: ['crm', 'user', 'placement'],
    appUrl: 'https://app-abc12345.vibecode.bitrix24.tech',
  }),
})

const { data } = await res.json()
// Ключ возвращается только один раз; файл доступен только владельцу
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-приложение

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.tech/v1/apps', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Дашборд продаж',
    scopes: ['crm', 'user', 'placement'],
    appUrl: 'https://app-abc12345.vibecode.bitrix24.tech',
  }),
})

const { data } = await res.json()
// Ключ возвращается только один раз; файл доступен только владельцу
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)

Поля ответа

Пример ответа

rawKey показан с усечённым секретом — это не рабочее значение.

{
  "success": true,
  "data": {
    "id": "33c4d5e6-f7a8-49b0-1234-5c6d7e8f9012",
    "title": "Дашборд продаж",
    "description": null,
    "scopes": ["crm", "user", "placement"],
    "handlerUrl": "https://vibecode.bitrix24.tech/v1/bitrix-handler",
    "appUrl": "https://app-abc12345.vibecode.bitrix24.tech",
    "redirectUris": [
      "https://vibecode.bitrix24.tech/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"
  }
}

Пример ответа при ошибке

400 — нарушена валидация:

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

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

• Потерянные не-ASCII символы в названии платформа называет. Строка, отправленная без явной сериализации в UTF-8, приходит с вопросительными знаками вместо букв: байты теряются на стороне клиента, до отправки запроса. Так отправляет строки Windows PowerShell. Приложение создаётся как есть, а в ответе появляется warnings с именем поля — название уезжает в карточку каталога Битрикс24 при публикации, поэтому чинить его лучше сразу. Готовый вызов с UTF8.GetBytes — Windows / PowerShell и UTF-8.
• Создаётся пара: приложение и API-ключ. Регистрация заводит запись приложения и парный ключ авторизации в один приём. Это влияет на удаление: ключ освобождает слот в пределе на пользователя только после удаления приложения.
• Скоупы приложения и скоупы парного ключа — разные наборы. В scopes вы объявляете доступ к данным портала Битрикс24 — crm, user, placement. Если набор прав вызывающего ключа не зафиксирован, парный ключ получает этот набор и дополнительно четыре платформенных скоупа: vibe:infra — серверы и агенты, vibe:ai — вызовы моделей, vibe:search — веб-поиск и исследование, vibe:storage — объектное хранилище. Тогда ключ авторизации сразу создаёт серверы через POST /v1/infra/servers, хотя в теле создания слова vibe:infra не было. Ответ в data.scopes показывает объявление приложения, а не итоговый набор ключа — итоговый смотрите в data.scopes ответа GET /v1/me, вызванного этим ключом.
• Ключ с зафиксированным набором прав выдаёт парному ключу ровно объявленное. Набор зафиксирован у партнёрского ключа, проектного ключа Cowork, личного ключа из формы кабинета и ключа, выписанного с exactScopes: true — Менеджмент-ключи. Приложение, созданное таким ключом, получает парный ключ ровно с тем, что стоит в scopes, — платформенные скоупы к нему не добавляются. Нужна инфраструктура: перечислите vibe:infra в scopes при создании, иначе POST /v1/infra/servers ответит 403 INFRA_SCOPE_REQUIRED. То же для vibe:ai, vibe:search и vibe:storage. Объявить можно только то право, которое есть у самого вызывающего ключа, иначе ответ — 403 SCOPE_GRANT_REQUIRES_CONSENT. Дописать право позже обновлением приложения не получится: перенос vibe:* до ключа с зафиксированным набором не доходит.
• Отличить ключ с зафиксированным набором прав можно до создания приложения. Вызовите GET /v1/me тем ключом, которым собираетесь создавать. Набор зафиксирован, если data.scopes совпадает с тем, что было отмечено при выдаче ключа. У остальных ключей в наборе стоят vibe:ai и vibe:search, даже когда их не отмечали.
• Приложение открывается в интерфейсе аккаунта. Регистрация объявляет аккаунту Битрикс24, что у приложения есть интерфейс, поэтому после создания приложение появляется в меню аккаунта, а с mobile: true — и в мобильном клиенте. Режим задаётся при создании и обновлением приложения не меняется. Приложение, которое в меню не появилось, зарегистрировано как работающее только по API: снимите режим «только API» в карточке приложения на аккаунте Битрикс24 либо создайте приложение заново.
• Признак mobile можно задать только при создании. PATCH /v1/apps/:id поле mobile не принимает — присланное значение игнорируется, см. Обновить приложение. Для уже созданного приложения признак включается в карточке приложения на портале Битрикс24 либо приложение создаётся заново.

Смотрите также

• Приложения
• Обновить приложение
• Удалить приложение
• Опубликовать
• Скоупы
• Ключи и авторизация
• Права на создание ключей и приложений