Для AI-агентов: markdown этой страницы — /docs-content/apps/create.md индекс документации — /llms.txt

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

POST /v1/apps

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

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

Поле	Тип	Обяз.	Описание
`title`	string	да	Название приложения, от 1 до 255 символов
`scopes`	array	да	Набор скоупов приложения — доступ к данным портала Битрикс24, минимум один. Для будущей публикации в наборе нужен `placement`. Скоупы платформы `vibe:*` перечислять не нужно, их выдаёт сама платформа. Список — Скоупы
`description`	string	нет	Описание приложения, до 2000 символов
`appUrl`	string	нет	Адрес приложения, только `http://` или `https://`. Пустая строка сохраняется как `null`
`redirectUris`	array	нет	Адреса перенаправления для OAuth. По умолчанию — адрес завершения авторизации и `http://localhost`
`mode`	string	нет	Режим доступа парного ключа: `READONLY` или `READWRITE`. По умолчанию берётся из политики портала

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

Примеры

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

Terminal

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-приложение

Terminal

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 — личный ключ

javascript

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()
// Сохраните data.rawKey сразу — он возвращается только один раз
console.log('App ID:', data.id)

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

javascript

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()

Поля ответа

Поле	Тип	Описание
`data.id`	string	Идентификатор приложения
`data.title`	string	Название
`data.description`	string \| null	Описание
`data.scopes`	array	Набор скоупов приложения — то, что вы передали в теле. Скоупы парного ключа шире, см. «Известные особенности»
`data.handlerUrl`	string	Адрес обработчика, задан платформой
`data.appUrl`	string \| null	Адрес приложения
`data.redirectUris`	array	Адреса перенаправления для OAuth
`data.bitrixClientId`	string \| null	Идентификатор OAuth-клиента на портале
`data.authorId`	string	Идентификатор автора
`data.portalId`	string	Идентификатор портала
`data.createdAt`	string	Дата создания, ISO 8601
`data.updatedAt`	string	Дата изменения, ISO 8601
`data.placements`	array	Места встраивания, до публикации пустой
`data.catalogStatus`	string	Статус в каталоге. У нового приложения — всегда `PRIVATE`
`data.publishedAt`	string \| null	Дата публикации, ISO 8601. У нового приложения — `null`
`data.rawKey`	string	Готовый ключ авторизации `vibe_app_…`. Единственное значение `vibe_app_…` в этом ответе — используйте именно его как `X-Api-Key`. Возвращается только в этом ответе и больше не показывается

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

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

JSON

{
  "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",
    "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,
    "rawKey": "vibe_app_local_7c3d4e5f6a7b80_55556666_…_6666"
  }
}

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

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