Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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:
{
"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:
{
"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 — превышен лимит выпуска токенов. Счёт ведётся в базе, поэтому число в ответе точное:
{
"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) — см. Что приходит в приложение.