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

`GET /v1/me`

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

Форма ответа зависит от типа ключа. Как ключ передаётся в запросе — [Передача ключа](/docs/keys-auth#передача-ключа).

## Параметры

| Параметр | Тип | Обяз. | Значения | Описание |
|----------|-----|:-----:|----------|---------|
| `refresh` (query) | string | нет | `tariff` | Форсирует повторную проверку тарифа портала в Битрикс24 перед формированием ответа. Работает только для ключей, привязанных к порталу. Без параметра ответ отдаётся из серверного кэша. |

## Примеры

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

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

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

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

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

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

```javascript
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` — при загрузке файлов.

| Поле | Тип | Тип ключа | Описание |
|------|-----|-----------|---------|
| `success` | boolean | все | Всегда `true` при успехе |
| `data.type` | string | все | Тип ключа: `personal`, `oauth_app` или `management` |
| `data.portal` | string | `vibe_api_`, `vibe_app_` | Домен привязанного портала Битрикс24 |
| `data.tariff` | object | все | Тариф портала: `code`, `name`, `isCommercial`, `wasEverCommercial`, `checkedAt`, `kind` |
| `data.tariff.checkedAt` | string | все | Время последней проверки тарифа в формате ISO 8601. Обновляется при вызове с `?refresh=tariff` |
| `data.scopes` | array | все | Скоупы ключа. Подбор набора — [Скоупы](/docs/scopes) |
| `data.accessMode` | string | все | Режим доступа ключа: `READWRITE` или `READONLY`. Подробнее — [Режим доступа](/docs/keys-auth/access-mode) |
| `data.capabilities` | object | все | Матрица доступных операций. Ключи первого уровня — группы, внутри каждой группы — слоты-операции. Строение слота описано ниже |
| `data.capabilities.apps` | object | все | Слоты-операции `create` — создать приложение, `publish` — опубликовать в каталоге, `bindPlacements` — привязать места встраивания. Плюс `sourceStorage` — не операция, а блок настроек хранилища исходников со своим набором полей |
| `data.capabilities.apps.sourceStorage` | object | все | Настройки хранилища исходников: `enabled`, `requiredBeforeDeploy`, `automaticOnDeploy`, `freshnessWindowMinutes`, `limits.maxBlobBytes`, `endpoint`, `mcpToolName`, `contentTypes`, `docs`. Полей `available` и `reason` у этого блока нет |
| `data.capabilities.servers` | object | все | Слоты `create` — создать сервер, `deploy` — опубликовать исходники, `preview` — выписать ссылку предпросмотра, `wake` — разбудить |
| `data.capabilities.agents` | object | все | Слот `create` — создать AI-агента |
| `data.capabilities.managedBots` | object | все | Слот `create` — создать управляемого бота |
| `data.capabilities.aiRouter` | object | все | Слоты `chatCompletions` — вызовы моделей, `byok` — работа со своим ключом провайдера |
| `data.capabilities.<группа>.<слот>.available` | boolean | все | Доступна ли операция этому ключу на этом портале прямо сейчас |
| `data.capabilities.<группа>.<слот>.reason` | string | все | Код состояния слота. Приходит и при `available: true` — `COMMERCIAL`, `TRIAL_ACTIVE`, — и при отказе — например `SESSION_REQUIRED`, `WRITE_BLOCKED_READONLY_KEY`, `MARKETPLACE_REQUIRED`, `BILLING_EXHAUSTED`, `FEATURE_DISABLED`, `INFRA_NOT_PERMITTED`, `SERVER_CREATION_DISABLED`, `SERVER_CREATION_ADMINS_ONLY`, `INT_TARIFF_REQUIRED`, `COMMERCIAL_PLAN_REQUIRED`, `TRIAL_PORTAL_LIMIT`, `PLAN_NOT_ALLOWED_ON_TRIAL`. Набор расширяется — обрабатывайте незнакомый код как отказ, опираясь на `available` |
| `data.capabilities.<группа>.<слот>.userMessage` | string | все | Готовый текст на языке пользователя. Приходит при отказе, показывайте его как есть |
| `data.capabilities.<группа>.<слот>.note` | string | все | Условие, которое `available: true` не покрывает: требование на стороне Битрикс24, счётчик занятых мест лимита или ограничение бесплатного доступа |
| `data.webResearch.promptForAgents` | string | все | Готовая подсказка для агента: как вызывать исследование и где смотреть каталог провайдеров |
| `data.capabilities.<группа>.<слот>.limits` | object | все | Действующие ограничения слота — например `allowedPlans` и `maxPortalTotal` при бесплатном доступе |
| `data.capabilities.<группа>.<слот>.alternatives` | array | все | Что сделать вместо заблокированной операции: элементы с полями `type`, `description`, `url` или `endpoint` |
| `data.api` | object | все | Правила работы с API в массиве `_rules`, список сущностей entity API в `entityApi`, ссылка на полный справочник |
| `data.rateLimit` | object | все | Действующие для ключа лимиты запросов, поле `requestsPerSecond`. Подробнее — [Лимиты запросов](/docs/keys-auth#лимиты-запросов) |
| `data.ai` | object | все | Доступ к AI Router: модель по умолчанию, доступные модели, размер каталога. Подробнее — [AI](/docs/ai) |
| `data.webSearch` | object | все | Провайдеры веб-поиска и их стоимость. Подробнее — [Список провайдеров](/docs/search/providers) |
| `data.webResearch` | object | все | Глубокое исследование: `available`, `endpoint`, `providers`, `defaultProvider`, `streaming`, `docs`. Подробнее — [Глубокое исследование](/docs/search/research) |
| `data.webResearch.providers[].cost` | object | все | Стоимость одного исследования у провайдера: `research` — цена в Вайбах (Ꝟ), `currency` — единица списания. У провайдера на своём ключе `research` равен `0` |
| `data.storage` | object | все | Объектное хранилище: использование, тарифы, эндпоинты загрузки. Подробнее — [Хранилище](/docs/storage) |
| `data.deployment` | object | все | Контракт публикации приложений, зависит от типа целевого сервера. Подробнее — [Публикация](/docs/infra/deploy) |
| `data.infra` | object | все | Инфраструктура: провайдеры, лимит серверов, список нездоровых серверов. Подробнее — [Инфраструктура](/docs/infra) |
| `data.feedback` | object | все | Эндпоинты и лимиты обратной связи. Подробнее — [Обратная связь](/docs/feedback) |
| `data.auth` | object | все | Как передать ключ в запросе: заголовки, а для ключа авторизации — шаги OAuth-авторизации |
| `data.quickstart` | object | все | Короткий список первых вызовов для знакомства с API |
| `data.docs` | string | все | Ссылка на полный справочник API — `GET /v1/guide` |
| `data.errorCodes` | object | все | Формат ответа при ошибке и ссылка на полный справочник кодов |
| `data.changelog` | object | все | Ссылка на журнал изменений API |
| `data.expiresAt` | string или null | `vibe_api_` | Срок действия ключа. `null` — без ограничения |
| `data.owner` | object | `vibe_api_` | Владелец ключа: `name`, `userId` |
| `data.portalEmbedding` | object | `vibe_api_` | Пояснение, что личный ключ не встраивает приложение в интерфейс портала |
| `data.app` | object | `vibe_app_` | Привязанное приложение: `title`, `id` |
| `data.currentUser` | object или null | `vibe_app_` | Пользователь Битрикс24, от лица которого идёт запрос. Заполняется при переданном токене сессии, без него приходит `null` |
| `data.placements` | object | `vibe_app_` | Встраивание приложения в интерфейс портала: доступные и зарегистрированные размещения, эндпоинты, порядок приёма запросов. Подробнее — [Встраивание приложения в портал](/docs/keys-auth#встраивание-приложения-в-портал) |
| `data.placements.bindPrerequisite` | object | `vibe_app_` | Условие на стороне Битрикс24, без которого [привязка места встраивания](/docs/apps/placements/bind) не пройдёт. Состав блока зависит от региона и типа портала |
| `data.placements.bindPrerequisite.subscriptionRequired` | boolean | `vibe_app_` | `true` — порталу нужна активная подписка Маркетплейса Битрикс24, коммерческого тарифа недостаточно. `false` — достаточно коммерческого тарифа Битрикс24 |
| `data.placements.bindPrerequisite.note` | string | `vibe_app_` | Текст с описанием условия и способом его выполнить |
| `data.placements.bindPrerequisite.errorCodes` | array | `vibe_app_` | Коды, которыми привязка ответит при невыполненном условии. `BITRIX_UNAVAILABLE` приходит в обоих случаях. К нему добавляются `B24_MARKET_SUBSCRIPTION_REQUIRED` и `B24_MARKET_TRIAL_USED` при `subscriptionRequired: true`, либо `INT_TARIFF_REQUIRED` при `false`. На коробочном портале в набор добавляется `SESSION_REQUIRES_ADMIN` |
| `data.oauth` | object | `vibe_app_` | URL и обязательные параметры OAuth-авторизации |
| `data.oauthTutorial` | object | `vibe_app_` | Пошаговый порядок OAuth-авторизации |
| `data.eventDelivery` | object | `vibe_app_` | Серверный приём событий портала без опроса |
| `data.schemaDiscovery` | object | `vibe_app_` | Как прочитать схему полей без токена сессии |

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

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

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

```json
{
  "success": true,
  "data": {
    "type": "personal",
    "portal": "mycompany.bitrix24.ru",
    "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_`) без токена сессии — показаны блоки, которых нет у личного ключа:

```json
{
  "success": true,
  "data": {
    "type": "oauth_app",
    "portal": "mycompany.bitrix24.ru",
    "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 — неверный ключ:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `INVALID_API_KEY` | Ключ не найден |
| 401 | `KEY_INACTIVE` | Ключ отозван |
| 401 | `KEY_EXPIRED` | Срок действия ключа истёк |
| 403 | `IP_NOT_ALLOWED` | Запрос с адреса вне списка разрешённых IP |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

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

**У ключа в режиме «только чтение» шесть слотов `capabilities` приходят закрытыми.** Это `apps.create`, `apps.publish`, `apps.bindPlacements`, `servers.create`, `agents.create` и `managedBots.create` — все шесть отдают `available: false` и `reason: "WRITE_BLOCKED_READONLY_KEY"`. Остальные слоты, включая `servers.deploy`, `servers.preview`, `servers.wake` и обе операции `aiRouter`, режим доступа не затрагивает. Подробнее — [Режим доступа](/docs/keys-auth/access-mode).

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

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

- [Создание и использование ключа](/docs/keys-auth)
- [Справочник API для модели](/docs/keys-auth/guide)
- [Режим доступа](/docs/keys-auth/access-mode)
- [Скоупы](/docs/scopes)
- [Менеджмент-ключи](/docs/management-keys)
- [Ошибки](/docs/errors)