Самоописание ключа

GET /v1/me

Возвращает самоописание ключа, которым выполнен запрос: его тип, привязанный портал, тариф и доступные на портале возможности платформы. Скоуп не нужен — эндпоинт отвечает на любой действующий ключ и служит для AI-модели стартовой точкой знакомства с порталом.

Форма ответа зависит от типа ключа. Как ключ передаётся в запросе — Передача ключа.

Параметры

Примеры

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

curl https://vibecode.bitrix24.tech/v1/me \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl https://vibecode.bitrix24.tech/v1/me \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/me', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Тип ключа:', data.type, '· портал:', data.portal)

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/me', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Поля ответа

Ответ описывает ключ, а не сущность портала. Верхнеуровневые блоки data.* — это карта возможностей: часть блоков общая для всех ключей, часть появляется только у ключа определённого типа. В колонке «Тип ключа» указано, для какого ключа блок присутствует.

Если вы знакомитесь с ключом впервые, достаточно четырёх блоков. type говорит, каким ключом вы работаете. scopes — к каким данным есть доступ. accessMode — разрешена ли запись. capabilities — какие операции доступны на этом портале и по какой причине отказано в остальных. Остальные блоки нужны под конкретную задачу: deployment и infra — при работе с серверами, ai и webSearch — при вызовах моделей, storage — при загрузке файлов.

Менеджмент-ключ (vibe_live_) возвращает другой набор блоков — portals, totalAppKeys, урезанный capabilities — и не несёт данных портала. Описание — Менеджмент-ключи.

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

Личный ключ (vibe_api_) — показаны основные поля:

{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.ru",
    "portalId": "8c3d1e04-…",
    "tariff": {
      "code": "ru_basic",
      "name": "Базовый",
      "isCommercial": true,
      "wasEverCommercial": true,
      "checkedAt": "2026-07-08T08:57:58.270Z",
      "kind": "CLOUD"
    },
    "scopes": ["crm", "task", "tasks", "im", "imbot", "disk", "user"],
    "accessMode": "READWRITE",
    "capabilities": {
      "apps": {
        "create": { "available": true },
        "publish": { "available": true },
        "bindPlacements": { "available": true }
      },
      "servers": {
        "create": { "available": true, "reason": "COMMERCIAL" },
        "deploy": { "available": true, "reason": "COMMERCIAL" },
        "preview": { "available": true },
        "wake": { "available": true }
      },
      "agents": {
        "create": {
          "available": true,
          "reason": "COMMERCIAL",
          "note": "Agent servers count toward the portal's infrastructure limit (currently 2/10)."
        }
      },
      "managedBots": {
        "create": {
          "available": true,
          "reason": "COMMERCIAL",
          "note": "Managed bot servers count toward the portal infrastructure limit."
        }
      },
      "aiRouter": {
        "chatCompletions": { "available": true },
        "byok": { "available": true }
      }
    },
    "owner": { "name": "Иван Петров", "userId": "1" },
    "expiresAt": null
  }
}

У слотов apps.publish и apps.bindPlacements поле note приходит всегда — в примере выше оно опущено, полный текст возвращает сам эндпоинт.

Ключ авторизации (vibe_app_) без токена сессии — показаны блоки, которых нет у личного ключа:

{
  "success": true,
  "data": {
    "type": "oauth_app",
    "portal": "mycompany.bitrix24.ru",
    "portalId": "8c3d1e04-…",
    "accessMode": "READWRITE",
    "app": { "title": "CRM Dashboard", "id": "f2342f7a-…" },
    "currentUser": null,
    "placements": {
      "available": true,
      "registered": ["LEFT_MENU"],
      "endpoints": [
        "POST https://vibecode.bitrix24.tech/v1/placements/bind",
        "POST https://vibecode.bitrix24.tech/v1/placements/unbind",
        "GET https://vibecode.bitrix24.tech/v1/placements",
        "GET https://vibecode.bitrix24.tech/v1/placements/available"
      ],
      "bindPrerequisite": {
        "subscriptionRequired": true,
        "note": "Binding a placement requires a Bitrix24-side prerequisite that depends on the dispatch path…",
        "errorCodes": [
          "B24_MARKET_SUBSCRIPTION_REQUIRED",
          "B24_MARKET_TRIAL_USED",
          "BITRIX_UNAVAILABLE"
        ]
      }
    }
  }
}

oauth.authorizeUrl — это шаблон, а не готовая ссылка. Эндпоинт /v1/oauth/authorize требует обязательный параметр state (16–512 символов) — это CSRF-токен по RFC 6749 §10.12, который генерирует клиент: создайте криптослучайную строку, добавьте её в URL и сверьте значение, вернувшееся в callback. Сервер не может сгенерировать state за вас — иначе защита от CSRF не работает. Открытие authorizeUrl как есть вернёт 400 INVALID_REQUEST "state: Required". Опционально добавьте redirect_uri — ваш адрес возврата, без него используется встроенная страница /oauth/complete, — и scope. Пример полной ссылки:

Скопировать

https://vibecode.bitrix24.tech/v1/oauth/authorize?app_key=vibe_app_…&state=aAbBcCdDeEfFgGhH&redirect_uri=https://myapp.com/callback

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

401 — неверный ключ:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Ошибки

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

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

?refresh=tariff проверяет тариф не чаще одного раза в минуту. Параметр форсирует живую проверку тарифа портала в Битрикс24 и сбрасывает кэш ответа. Если предыдущая проверка была меньше минуты назад, запрос возвращает уже известное значение без новой проверки. Для менеджмент-ключа параметр не делает ничего — такой ключ не привязан к порталу.

Ответ кэшируется на стороне сервера около 30 секунд. Смена скоупов или режима доступа отражается в ответе сразу. Тариф, баланс и состояние инфраструктуры обновляются при первом чтении после истечения кэша. Запрос с ?refresh=tariff сбрасывает кэш, и следующее чтение без этого параметра отдаёт свежий тариф.

У ключа в режиме «только чтение» часть слотов capabilities приходит закрытыми. Это apps.publish, apps.bindPlacements, servers.create, servers.wake, agents.create, managedBots.create и обе операции aiRouter — все они отдают available: false и reason: "WRITE_BLOCKED_READONLY_KEY". Слот servers.deploy в этот список не входит: доставка на уже свой сервер такому ключу разрешена. У ключа «только чтение» в корне ответа приходит и поле writeRestriction — код WRITE_BLOCKED_READONLY_KEY, область действия и ссылка на страницу про режимы. Поле появляется только пока запрет включён: платформенный админ вправе его снять, и тогда поле из ответа исчезает вместе с самим запретом. Внутри поля есть список exceptions — маршруты, которые центральный запрет не трогает. Читайте состав из ответа, а не из этой страницы: там POST /v1/apps, где ключом «только чтение» создаётся приложение в том же режиме, два не-GET адреса, которые записью не являются — DELETE /v1/cowork/key (аварийный отзыв ключа) и DELETE /v1/infra/servers/{id}/lock (снятие залипшего лока, причём БЕЗУСЛОВНОЕ, — второй шаг, допустимый лишь после независимо подтверждённого простоя сервера; поле recoveryAction ответа EXEC_BUSY указывает не на него, а на POST /v1/infra/servers/{id}/unstick), — и пять операций на свой сервер: деплой, выполнение команд, загрузка файла, иконка приложения и снятие залипшего exec-лока (POST /v1/infra/servers/{id}/unstick, восстановление ровно для разрешённых операций). У управляющего ключа поле тоже приходит, но снять его нельзя ничем: запрет записи для таких ключей безусловен. Оно нужно потому, что тело ответа называет пишущие ручки в трёх десятках мест (подсказки хранилища, обращений, автосохранения исходников, коворка): это адреса, а не разрешения. Доступность конкретной операции — в capabilities.

Слот apps.create закрытым НЕ приходит: приложение в режиме READONLY таким ключом создаётся, а запрет на режим READWRITE описан в поле note этого слота. Чтения режим не затрагивает — например, servers.preview. Подробнее — Режим доступа.

Название тарифа предназначено для показа, а не для сравнения. Поле data.tariff.name собирается при чтении и может меняться, не меняя самого тарифа. Платформа берёт его по такому порядку. Если код тарифа известен справочнику редакций — оттуда, на русском языке. Иначе — название лицензии, как его сообщил Битрикс24, на языке портала. Иначе — сохранённое ранее название. Иначе — null. Из этого следуют три вещи. Первая: null — штатное значение, а не ошибка. Вторая: название не зависит от того, кто спрашивает, — его не меняют ни Accept-Language, ни язык интерфейса владельца ключа. Третья: код тарифа вместо названия не подставляется никогда — если названия нет, приходит null, а не pro100. Ветвить логику нужно по data.tariff.code, isCommercial и kind. Подписи известных редакций при этом уточнены — три из них: «Демо» стало «Демо-период», «Проект» — «Проект — архивный бесплатный», «NFR» — «NFR — партнёрская лицензия».

Признак wasEverCommercial — история, а не доступ. Значение true означает лишь, что портал когда-либо наблюдался на коммерческом тарифе. Доступа к инфраструктуре и режиму OPEN признак не даёт и отказов в этом доступе не снимает: доступ считается только по текущему состоянию портала — тарифу, подписке и демо. Решение принимайте по capabilities в этом же ответе, а не по признаку.

Признак wasEverCommercial не односторонний. Понижение тарифа значение не сбрасывает, но платформа может сменить его с true на false, если оснований под признаком не нашлось. Логику, которая считает переход возможным только в одну сторону, на этом поле строить нельзя.

Модель размещения определяйте по блоку deployment, а не по тарифу портала. На бесплатном тарифе Битрикс24 новая галактика не создаётся. Если режим галактик включён, но хоста нет, deployment.galaxyApp отсутствует, deployment.primary равен standalone, а deployment.placementNote описывает двухшаговый путь. Он доступен, только когда capabilities.servers.create.available в том же ответе равен true. Допустимый идентификатор тарифа выберите из capabilities.servers.create.limits.allowedPlans. При выключенном режиме галактик placementNote отсутствует, одношаговый запрос с source возвращает 400 SOURCE_AT_CREATE_GALAXY_ONLY, а возможность двухшагового пути определяется тем же слотом capabilities. Если существующий хост проходит предварительную проверку сохранённого состояния, блок galaxyApp присутствует и одношаговое создание с source стоит попробовать. Это не гарантия: текущую вместимость проверяет только POST /v1/infra/servers.

Если существующий хост не проходит предварительную проверку, блок galaxyApp отсутствует. Пока capabilities.servers.create.available равен false, placementNote запрещает двухшаговое создание отдельной машины: при включённом контроле trial-ограничений занятый слот даёт 402 TRIAL_PORTAL_LIMIT. Для нового одношагового запроса дождитесь восстановления хоста, попросите администратора починить его либо повысьте тариф. После удаления хоста заново прочитайте GET /v1/me и используйте объявленный там двухшаговый путь. Следуйте подсказке фактического ответа POST. Порядок вызовов — Создать сервер и Публикация.

Без ключа в браузере эндпоинт отдаёт HTML. Запрос GET /v1/me без заголовка X-Api-Key и с заголовком Accept: text/html возвращает страницу-заглушку со статусом 200, а не JSON. Запрос с ключом или без text/html в заголовке Accept всегда получает JSON-самоописание.

Карта требуемых прав

Раньше границу ключа можно было узнать только вызовом: запрос уходил и возвращался отказом 403 SCOPE_DENIED, называющим недостающее право. Список доступных сущностей показывал только открытое, а закрытое просто отсутствовало — и по отсутствию нельзя было отличить «такой сущности нет в продукте» от «она есть, но вашему ключу закрыта».

Блок data.api.scopeRequirements отвечает на этот вопрос до вызова:

{
  "granted": { "bitrix24": ["imbot"], "platform": ["vibe:ai", "vibe:search"] },
  "missing": {
    "bitrix24": {
      "crm": {
        "entities": ["deals", "contacts", "companies", "leads"],
        "unlocks": ["/v1/duplicates/find", "/v1/addresses"],
        "unlocksRemaining": 41,
        "truncated": true,
        "howToObtain": "reissue-key"
      }
    },
    "platform": {}
  }
}

Права Битрикс24 закрепляются за ключом в момент выпуска, поэтому howToObtain у них — reissue-key: добавить право в настройках уже выпущенного ключа недостаточно, нужен перевыпуск. Права Вайбкод правятся в кабинете.

Карта описывает только проверку прав на стороне платформы. Она не обещает, что вызов пройдёт. Право, выданное в кабинете уже после выпуска ключа, попадёт в карту, но Битрикс24 его не признает и ответит BITRIX_ACCESS_DENIED. Отказы по виду ключа, владению, режиму только для чтения, заморозке и тарифу — отдельные оси, и в карте они не описаны. Об этом же предупреждает поле _note внутри блока.

Перечень путей пока неполон, и карта говорит об этом сама. Поле coverage.paths со значением partial означает, что часть кастомных роутов ещё не имеет машинного вердикта, поэтому unlocks и unlocksRemaining занижают. Отсутствие пути в списке НЕ доказывает, что путь не гейтится: если вызов всё-таки отвечает отказом по правам, верьте отказу, а не карте. Список сущностей при этом полон всегда.

Отбивка не изменилась: вызов без нужного права по-прежнему возвращает 403 SCOPE_DENIED с именем этого права. Карта добавлена как предварительная проверка, а не как замена отбивки.

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

• Ключи и авторизация
• Справочник API для модели
• Режим доступа
• Скоупы
• Менеджмент-ключи
• Ошибки