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

Выпустить токен доступа

POST /v1/infra/servers/:id/access-tokens

Выпускает краткосрочный токен для внешнего доступа к развёрнутому приложению. Два режима: api-bearer — JWT для HTTP-заголовка Authorization. share-url — ссылка, при переходе по которой устанавливается куки.

Ключ команды разработки с ролью ADMIN или DEVELOPER выпускает только api-bearer. При первом запросе передайте ttlSeconds от 300 до 600. При повторе одобренной операции передайте точный expiresAt из retryOperation и ID одобренного запроса в approvalId, без ttlSeconds. Порядок согласования — Согласование расширения доступа.

Восстановление зависит от вызывающего ключа. После 410 TOKEN_EXPIRED запись токена могла сохраниться, хотя JWT не возвращён. Перед новым выпуском сверьте список токенов с status=all, используя ключ, управляющий сервером. Если вызов выполнен ключом команды разработки, попросите владельца управляющего ключа выполнить сверку. Ключ команды разработки не может обновлять токены через refresh или выпускать share-url. Для дальнейшего доступа нужен отдельно согласованный выпуск нового api-bearer.

Параметры

Параметр В Тип Обяз. Описание
Параметрid Вpath Типstring (UUID) Обяз.да ОписаниеID BLACKHOLE-сервера. Список: GET /v1/infra/servers

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

Поле Тип Обяз. По умолч. Описание
Полеmode Типstring Обяз.да По умолч.— Описание"api-bearer" или "share-url"
ПолеttlSeconds Типnumber Обяз.нет По умолч.86400 ОписаниеВремя жизни токена в секундах. Диапазон: 300–315 360 000 (от 5 минут до 10 лет). Значение 315 360 000 отображается в интерфейсе как «Бессрочно»
ПолеexpiresAt Типstring (ISO 8601) Обяз.нет По умолч.— ОписаниеПри повторе одобренного запроса — точное значение из retryOperation, без ttlSeconds
ПолеapprovalId Типstring (UUID) Обяз.нет По умолч.— ОписаниеID одобренного запроса из error.details.proposalId. Повторите исходное действие тем же ключом и с согласованными параметрами
ПолеidentityBound Типboolean Обяз.нет По умолч.true ОписаниеТолько для share-url. При true — потребует входа через Битрикс24, и в журнале окажется реальный идентификатор пользователя. При false — анонимный переход, синтетический идентификатор
Полеname Типstring Обяз.нет По умолч.— ОписаниеМетка токена для отображения в списке (до 100 символов)

Согласование доступа

Если выпуск расширяет круг доступа, первый запрос отвечает 409 AUDIENCE_APPROVAL_REQUIRED. В error.details приходят proposalId, approvalUrl, expiresAt и retryOperation. Токен на этом шаге не выпущен. Передайте ссылку человеку, который вправе согласовать доступ и вошёл в кабинет. API-ключ сам согласовать запрос не может. Тем же ключом проверьте состояние запроса. После APPROVED возьмите исходный HTTP body, удалите ttlSeconds, добавьте только expiresAt из retryOperation и approvalId, равный proposalId. Сам retryOperation не является HTTP body: его внутреннее поле type и режим в верхнем регистре отправлять нельзя. Не пересчитывайте срок и не меняйте режим, имя или привязку личности.

APPROVED означает согласие, а не выпуск токена. Если параметры или доступ изменились, либо согласование уже использовано или истекло, ориентируйтесь на код ошибки в таблице ниже. При 410 TOKEN_EXPIRED запись могла уже появиться, но JWT не возвращён: перед повтором попросите владельца ключа, управляющего сервером, перечитать список токенов с status=all и согласуйте дальнейший выпуск отдельно. Ключ команды разработки не может читать этот список.

Примеры

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-tokens" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "api-bearer",
    "ttlSeconds": 600,
    "name": "ci-smoke"
  }'

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-tokens" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "api-bearer",
    "ttlSeconds": 600,
    "name": "ci-smoke"
  }'

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

javascript
const requestBody = { mode: 'api-bearer', ttlSeconds: 600, name: 'ci-smoke' }
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access-tokens`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestBody),
  }
)
const result = await res.json()
if (!res.ok || result.success !== true) {
  if (res.status === 409 && result.error?.code === 'AUDIENCE_APPROVAL_REQUIRED') {
    const { proposalId, approvalUrl, retryOperation } = result.error.details
    const { ttlSeconds, ...sameIntent } = requestBody
    const retryBody = { ...sameIntent, expiresAt: retryOperation.expiresAt, approvalId: proposalId }
    // Передайте approvalUrl человеку; после APPROVED отправьте retryBody тем же ключом.
    console.log({ proposalId, approvalUrl, retryBody })
    throw new Error('Ожидается согласование доступа')
  }
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result

// E2E-проверка через публичный путь
const check = await fetch(`${data.appUrl}/api/health`, {
  headers: { Authorization: `Bearer ${data.token}` },
})
console.log(check.status) // 200 — приложение отвечает через Gateway

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

javascript
const requestBody = { mode: 'api-bearer', ttlSeconds: 600, name: 'ci-smoke' }
const res = await fetch(
  `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access-tokens`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestBody),
  }
)
const result = await res.json()
if (!res.ok || result.success !== true) {
  if (res.status === 409 && result.error?.code === 'AUDIENCE_APPROVAL_REQUIRED') {
    const { proposalId, approvalUrl, retryOperation } = result.error.details
    const { ttlSeconds, ...sameIntent } = requestBody
    const retryBody = { ...sameIntent, expiresAt: retryOperation.expiresAt, approvalId: proposalId }
    // Передайте approvalUrl человеку; после APPROVED отправьте retryBody тем же ключом.
    console.log({ proposalId, approvalUrl, retryBody })
    throw new Error('Ожидается согласование доступа')
  }
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result

// E2E-проверка через публичный путь
const check = await fetch(`${data.appUrl}/api/health`, {
  headers: { Authorization: `Bearer ${data.token}` },
})
console.log(check.status) // 200 — приложение отвечает через Gateway

Поля ответа

Набор полей зависит от режима.

Режим api-bearer:

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.id Типstring ОписаниеID токена для последующего отзыва
Полеdata.mode Типstring Описание"api-bearer"
Полеdata.token Типstring ОписаниеJWT для заголовка Authorization: Bearer. Сохраните его сразу: повторно эта же строка не отдаётся, свежий JWT для записи управляющего ключа выдаёт обновление токена. Ключ команды разработки не может обновлять токены, ему нужен отдельно согласованный новый выпуск
Полеdata.expiresAt Типstring (ISO 8601) ОписаниеСрок хранения записи токена — для листинга и отзыва
Полеdata.jwtExpiresAt Типstring (ISO 8601) ОписаниеРеальный срок действия Bearer-токена. Ограничен 10 минутами независимо от ttlSeconds. После истечения выпустите новый токен
Полеdata.note Типstring ОписаниеПояснение о разнице между expiresAt и jwtExpiresAt
Полеdata.subdomain Типstring ОписаниеСубдомен сервера
Полеdata.appUrl Типstring ОписаниеПолный HTTPS-адрес приложения
Полеdata.curlExample Типstring ОписаниеГотовый curl-пример с токеном для быстрой проверки

Режим share-url:

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.id Типstring ОписаниеID токена для последующего отзыва
Полеdata.mode Типstring Описание"share-url"
Полеdata.shortcode Типstring ОписаниеКод, вставляемый в URL как ?s=<shortcode>
Полеdata.url Типstring ОписаниеПолная распространяемая ссылка
Полеdata.identityBound Типboolean ОписаниеТребует ли переход входа через Битрикс24
Полеdata.expiresAt Типstring (ISO 8601) ОписаниеМомент истечения токена
Полеdata.name Типstring | null ОписаниеМетка, переданная при выпуске

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

Режим api-bearer:

JSON
{
  "success": true,
  "data": {
    "id": "9f1c4b7e-3d52-4a18-9c0e-7b2a1f6d84c3",
    "mode": "api-bearer",
    "token": "eyJhbGciOiJFUzI1NiJ9...",
    "expiresAt": "2026-05-18T10:50:00.000Z",
    "jwtExpiresAt": "2026-05-18T10:40:10.000Z",
    "subdomain": "app-91306a4c",
    "appUrl": "https://app-91306a4c.vibecode.bitrix24.tech",
    "curlExample": "curl -H \"Authorization: Bearer eyJhbGciOiJFUzI1NiJ9...\" https://app-91306a4c.vibecode.bitrix24.tech/api/health",
    "note": "JWT is a 10-minute Gateway session token. The row's `expiresAt` is the long-lived TTL for listing/revoking, but the Bearer token itself stops working at `jwtExpiresAt`. To keep a long-running client authenticated, POST /v1/infra/servers/:id/access-tokens/:tokenId/refresh before jwtExpiresAt to re-mint a fresh JWT for the SAME token (no new row — does not consume the active-token cap or mint rate-limit), or use mode=share-url for browser links that auto-refresh on each visit."
  }
}

Режим share-url:

JSON
{
  "success": true,
  "data": {
    "id": "2a7d5e61-84bc-4f39-b0d7-5e6c9a3f1b28",
    "mode": "share-url",
    "shortcode": "R8k3Zm2P",
    "url": "https://app-91306a4c.vibecode.bitrix24.tech/?s=R8k3Zm2P",
    "identityBound": false,
    "expiresAt": "2026-06-17T08:44:00.000Z",
    "name": "предпросмотр"
  }
}

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

429 — превышен лимит выпуска токенов. Счёт ведётся в базе, поэтому число в ответе точное:

JSON
{
  "success": false,
  "error": {
    "code": "TOKEN_MINT_RATE_LIMIT",
    "message": "Rate limit: 50 mints/hour per API key"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_MODE ОписаниеПередан недопустимый mode либо неверный тип значения в теле запроса
HTTP400 КодUNKNOWN_PARAM ОписаниеВ теле запроса есть неизвестное поле. Ответ содержит details со списком допустимых полей и подсказкой
HTTP400 КодINVALID_TTL ОписаниеttlSeconds вне допустимого диапазона [300, 315 360 000]. Для ключа команды разработки при первом запросе обязателен ttlSeconds от 300 до 600, при одобренном повторе — согласованный expiresAt с остатком не более 600 секунд
HTTP400 КодNAME_TOO_LONG Описаниеname превышает 100 символов
HTTP400 КодSERVER_NO_SUBDOMAIN ОписаниеУ сервера нет субдомена, обращаться не к чему
HTTP401 КодMISSING_API_KEY ОписаниеКлюч не передан через X-Api-Key или поддерживаемую схему Authorization: Bearer
HTTP401 КодINVALID_API_KEY ОписаниеКлюч авторизации не опознан
HTTP401 КодKEY_INACTIVE ОписаниеКлюч, которым сделан запрос, больше не активен
HTTP401 КодKEY_EXPIRED ОписаниеИстёк срок действия ключа API, которым сделан запрос; это не срок resource URL
HTTP401 КодNO_PORTAL ОписаниеКлюч, не являющийся управляющим, не привязан к порталу
HTTP401 КодCOWORK_CHAT_KEY_INACTIVE ОписаниеДля ключа чата Коворк/Код родительский ключ устройства больше не пригоден
HTTP401 КодWRONG_AUTH_SCHEME ОписаниеКлюч приложения OAuth передан как Bearer-сессия: передайте ключ в X-Api-Key, а сессию — в Authorization: Bearer
HTTP401 КодINVALID_SESSION ОписаниеПереданная сессия OAuth недействительна или истекла
HTTP401 КодTOKEN_EXPIRED ОписаниеТокен пользователя OAuth истёк, а его обновление не удалось; требуется повторная авторизация
HTTP401 КодTOKEN_INVALID ОписаниеПри включённом партнёрском контуре AI передан неизвестный или истёкший токен этого контура
HTTP401 КодKEY_REVOKED ОписаниеПартнёрский ключ, связанный с токеном контура AI, отозван
HTTP402 КодACCOUNT_FROZEN ОписаниеСчёт владельца ключа заморожен. При выключенной развязке долга общий гард API-ключа отказывает до обработчика. Для восстановления баланса используйте error.topupUrl; сам статус не разрешает повтор предыдущей записи
HTTP403 КодAUDIENCE_APPROVAL_FORBIDDEN ОписаниеТекущий источник выпуска не прошёл проверку полномочий: например, ключ, его владелец или портал больше не активны, членство владельца прекращено либо согласовавший человек утратил права. Токен не выпущен. Восстановите действующие права или используйте подходящий ключ; для согласования получите новое согласие человека с текущими правами
HTTP403 КодFEATURE_DISABLED ОписаниеВыпуск прошёл предварительную проверку до отключения раздела; свежая проверка внутри транзакции отказала. Токен не выпущен
HTTP403 КодTOKEN_OWNER_MISMATCH ОписаниеСервер принадлежит другому API-ключу. Исключение — ключ команды разработки с действующей ролью ADMIN или DEVELOPER на этом сервере.
HTTP403 КодSERVER_KEY_MISMATCH ОписаниеПока шёл выпуск, сервер перешёл на другой API-ключ — например, при перевыпуске ключа — или был удалён. Токен не выпущен. Перечитайте сервер через GET /v1/infra/servers/:id и выпускайте токен ключом, которому сервер принадлежит сейчас. Если сервер удалён, этот запрос ответит 404
HTTP403 КодPORTAL_COLLABORATOR_TOKEN_MODE_FORBIDDEN ОписаниеКлюч команды разработки запросил share-url. Такой ключ выпускает только api-bearer
HTTP403 КодAGENT_OWNER_ONLY ОписаниеСервер создан под AI-агента — токены доступа для него отключены
HTTP403 КодINFRA_FORBIDDEN_FOR_COWORK_KEY ОписаниеВызов сделан ключом Коворк/Код — такой ключ работает только с данными, изменяющие операции ему закрыты. Что делать — Проектный ключ для деплоя
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения не может выполнить запись
HTTP403 КодEXTERNAL_COLLABORATOR_KEY_OUT_OF_SCOPE ОписаниеОперация не входит в список доступных ключу внешнего участника. Используйте ключ, управляющий сервером
HTTP403 КодPORTAL_COLLABORATOR_KEY_WRONG_SERVER ОписаниеКлюч команды разработки привязан к другому серверу
HTTP403 КодPORTAL_COLLABORATOR_NOT_A_MEMBER ОписаниеЧленство в команде разработки прекращено или роль больше не открывает эту операцию
HTTP403 КодIP_NOT_ALLOWED ОписаниеIP вызывающего не входит в разрешённый список ключа
HTTP403 КодOWNER_BLOCKED ОписаниеВладелец ключа заблокирован
HTTP403 КодOWNER_DELETED ОписаниеВладелец ключа удалён
HTTP403 КодPORTAL_SUSPENDED ОписаниеПривязанный портал Битрикс24 приостановлен
HTTP403 КодPORTAL_DELETED ОписаниеПривязанный портал Битрикс24 удалён
HTTP403 КодPORTAL_BLOCKED ОписаниеПривязанный портал Битрикс24 заблокирован
HTTP403 КодMANAGEMENT_KEY_NO_ENTITY_ACCESS ОписаниеУ управляющего ключа нет необходимой привязки к порталу или прав доступа к его данным
HTTP403 КодAGENT_MAINTENANCE_KEY_OUT_OF_SCOPE ОписаниеВызов не входит в список маршрутов ключа обслуживания
HTTP403 КодAPP_API_KEY_OUT_OF_SCOPE ОписаниеВызов не входит в список маршрутов ключа приложения
HTTP403 КодWAITLIST_PENDING ОписаниеВладелец ключа ещё не активирован
HTTP403 КодSESSION_APP_MISMATCH ОписаниеСессия OAuth относится к другому приложению
HTTP403 КодPLANE_FORBIDDEN ОписаниеКлюч партнёра не разрешает этот AI-контур
HTTP403 КодSYSTEM_FORBIDDEN ОписаниеКлюч партнёра не разрешает эту AI-систему
HTTP403 КодSCOPE_FORBIDDEN ОписаниеAI-контур партнёра запрещает этот маршрут
HTTP403 КодCONNECT_COMPANY_DERIVED_TOKEN_FORBIDDEN ОписаниеКлюч подключения компании не может управлять производными токенами
HTTP403 КодCOWORK_READONLY ОписаниеМесто Коворк/Код доступно только для чтения
HTTP403 КодGALAXY_DISABLED ОписаниеОперации галактики выключены для этого портала
HTTP404 КодNOT_FOUND ОписаниеСервер не существует, удалён или принадлежит вызывающему ключу, но его портал деактивирован; либо approvalId не найден или недоступен вызывающему ключу
HTTP409 КодACTIVE_TOKEN_LIMIT ОписаниеДостигнут лимит 100 активных токенов на сервер
HTTP409 КодKEY_ROTATION_RECOVERY_REQUIRED ОписаниеЗамена API-ключа, которым сделан запрос, не завершена: его перевыпуск закончился ответом 500 или ещё не закончился. Токен не выпущен. Порядок действий — Перевыпустить API-ключ
HTTP409 КодAUDIENCE_APPROVAL_REQUIRED ОписаниеТребуется согласие человека. Используйте error.details.proposalId, approvalUrl и retryOperation по порядку согласования выше
HTTP409 КодAUDIENCE_APPROVAL_MISMATCH ОписаниеКлюч, параметры или ожидаемый результат не совпадают с согласованным действием. Не изменяйте одобренный повтор
HTTP409 КодAUDIENCE_APPROVAL_STALE ОписаниеСостав доступа или его версия изменились после создания запроса. Требуется новое согласование
HTTP409 КодAUDIENCE_APPROVAL_REPLAY ОписаниеСогласование уже использовано либо больше не доступно для применения. Перечитайте состояние запроса
HTTP410 КодAUDIENCE_APPROVAL_EXPIRED ОписаниеСрок согласования истёк. Создайте новый запрос и получите согласие заново
HTTP410 КодTOKEN_EXPIRED ОписаниеПосле сохранения записи срок токена истёк до подписи JWT. JWT не возвращён; попросите владельца управляющего ключа сверить список токенов с status=all перед повторным выпуском; ключ команды разработки не может читать список
HTTP429 КодQUOTA_EXCEEDED ОписаниеВключён платный учёт API с ненулевой ценой превышения квоты: суточная бесплатная квота исчерпана, баланс PREPAY неположительный. Пополните баланс. error.quota и error.used содержат счётчики; X-RateLimit-Quota, X-RateLimit-Used и X-RateLimit-Remaining — квоту, расход и нулевой остаток. Этот отказ не гарантирует Retry-After или X-RateLimit-Scope
HTTP429 КодCALLER_RATE_LIMITED ОписаниеОбщий лимит запросов ключа или пользователя. Подождите число секунд из Retry-After; X-RateLimit-Scope указывает отказавший уровень
HTTP429 КодTOKEN_MINT_RATE_LIMIT ОписаниеПревышен лимит 50 выпусков в час на API-ключ. Счёт ведётся в базе, между репликами не делится. Заголовок Retry-After: 3600
HTTP503 КодFEATURE_DISABLED ОписаниеРаздел токенов доступа выключен на платформе. Признак до вызова и запасной путь — Доступность
HTTP503 КодACCOUNT_PENDING_ERASURE ОписаниеВладелец ключа ожидает удаления или уже удаляется. Заголовок Retry-After: 3600
HTTP503 КодSERVICE_DISABLED ОписаниеAI-контур партнёра или сервис готовности его квоты выключен. Заголовок Retry-After для этого отказа не гарантирован
HTTP503 Кодuser_self_deletion_pending ОписаниеВладелец API-ключа запланировал удаление. Проверка раздела токенов отказывает до обработчика. Заголовок Retry-After: 604800

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

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

  • Выдача ссылки записывается в журнал доступа портала. Успешный выпуск в режиме share-url попадает в журнал, когда сервер привязан к порталу, и от настроек портала не зависит. Смотреть журнал и получать уведомления администратор может там, где платформа открыла порталу раздел «Приложения»: тогда администратор видит в нём, что приложение открыли ссылкой, а если ссылка не требует входа в Битрикс24, то есть identityBound равен false, и приложение до этого не было открыто наружу — администраторы дополнительно получают сообщение в чат-бот со ссылкой на список открытых приложений. Формат запроса, ответа и коды отказов при этом не меняются.
  • Для токенов управляющего ключа продление доступа дешевле повторного выпуска. Обновление токена выдаёт свежий JWT для той же записи и не расходует ни лимит активных токенов, ни лимит выпусков в час.
  • У api-bearer идентификатор в журнале всегда один. Это UUID владельца API-ключа, поле identityBound на него не влияет и в ответе списка приходит как true.
  • api-bearer подтверждает, что запрос сделан владельцем ключа, но не создаёт сессию пользователя Битрикс24. Токен аутентифицирует запрос как владельца API-ключа и открывает доступ к приложению по его политике доступа. Он не подставляет заголовок X-Vibe-Authorization и не даёт currentUser в ответе GET /v1/me. Поэтому маршрут приложения, который проверяет администратора Битрикс24 через X-Vibe-Authorization и GET /v1/me, под api-bearer-токеном получит currentUser: null. Такому маршруту нужна полноценная авторизация пользователя через OAuth-приложение (placement) — см. Что приходит в приложение.

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