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

POST /v1/apps

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

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

Поле Тип Обяз. Описание
title string да Название приложения, от 1 до 255 символов
scopes array да Набор скоупов, минимум один. Для будущей публикации в наборе нужен placement. Список — Скоупы
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.prefix string Префикс ключа
data.suffix string Суффикс ключа
data.authorId string Идентификатор автора
data.portalId string Идентификатор портала
data.createdAt string Дата создания, ISO 8601
data.updatedAt string Дата изменения, ISO 8601
data.placements array Места встраивания, до публикации пустой
data.rawKey string Готовый ключ авторизации vibe_app_…. Возвращается только в этом ответе и больше не показывается

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

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",
    "prefix": "vibe_app_local_7c3",
    "suffix": "6666",
    "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": [],
    "rawKey": "vibe_app_local_7c3d4e5f6a7b80_55556666_…_6666"
  }
}

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

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

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

Ошибки

HTTP Код Описание
400 VALIDATION_ERROR Нарушена валидация тела: пропущено title, пустой scopes, недопустимый appUrl
403 APP_CREATION_RESTRICTED Создание приложений на портале ограничено списком, автор в него не входит
403 KEY_POLICY_READONLY_REQUIRED Политика портала разрешает только READONLY, запрошен READWRITE
409 KEY_LIMIT_REACHED Достигнут предел ключей на пользователя для портала

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

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

  • Ключ авторизации возвращается только один раз. Поле rawKey присутствует в ответе создания и больше нигде не отдаётся — ни в данных приложения, ни в списке. Не сохранили при создании — пересоздайте приложение.
  • Создаётся пара: приложение и API-ключ. Регистрация заводит запись приложения и парный ключ авторизации в один приём. Это влияет на удаление: ключ освобождает слот в пределе на пользователя только после удаления приложения.

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