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

Подписанная ссылка на ресурс

POST /v1/infra/servers/:id/access-tokens/:tokenId/resource-url

Выдаёт ссылку для GET/HEAD одного ресурса закрытого приложения: CSS, картинки или шрифта. Ссылка работает без браузерной сессии шлюза и не открывает остальные пути приложения. Любой, у кого есть ссылка, может прочитать указанный ресурс до истечения срока или отзыва родительского токена. Подписывайте только содержимое, которое намерены передать получателям виджета.

Нужен ключ, управляющий сервером, и существующий токен api-bearer, созданный этим ключом через выпуск токена, с требуемым одобрением аудитории. Новая запись токена не создаётся; срок и одобренная аудитория родителя не расширяются. Ключи команды разработки, внешнего участника и Коворк/Код не могут вызывать эту операцию. Доступность раздела проверяйте до вызова.

Известные сборщики предпросмотра ссылок получают локальную карточку публичного приложения или нейтральную страницу закрытого приложения; шлюз не отправляет их запрос через туннель даже при наличии ресурсной ссылки. Ресурсная ссылка не отменяет эту политику.

Параметры

Параметр Где Тип Обязателен Описание
Параметрid Гдеpath Типstring Обязателенда ОписаниеID сервера из списка серверов
ПараметрtokenId Гдеpath Типstring Обязателенда Описаниеdata.id существующего выпущенного токена api-bearer

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

Поле Тип Обязателен Описание
Полеpath Типstring Обязателенда ОписаниеАбсолютный ASCII-путь длиной от 2 до 1024 символов, например /widget/style.css. Корень / не допускается. Допустимы буквы, цифры, /, ., _, ~, -. Без query, fragment, %, // и сегментов ./... Зарезервированы /robots.txt, /_gw, /tunnel и все пути внутри /_gw/ и /tunnel/
ПолеttlSeconds Типinteger Обязателеннет Описание1–2592000 секунд, по умолчанию 86400. Итоговый срок ограничен сроком родителя

Лишние поля тела отклоняются с 400 INVALID_RESOURCE_REQUEST.

Примеры

Запускайте на сервере приложения: ключ и сессию пользователя не передавайте браузеру.

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/resource-url" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/widget/style.css","ttlSeconds":86400}'

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/resource-url" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"/widget/style.css","ttlSeconds":86400}'

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/resource-url', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ path: '/widget/style.css', ttlSeconds: 86400 }),
})
const result = await res.json()
if (!res.ok || result.success !== true) {
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result
// Передайте data.url в виджет и замените ссылку до data.expiresAt.

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/resource-url', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    Authorization: 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ path: '/widget/style.css', ttlSeconds: 86400 }),
})
const result = await res.json()
if (!res.ok || result.success !== true) {
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result
// Передайте data.url в виджет и замените ссылку до data.expiresAt.

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue
Полеdata Типobject ОписаниеПодписанный URL и его срок
Полеdata.url Типstring ОписаниеURL ресурса с параметром __resource; сохраните целиком
Полеdata.expiresAt Типstring (ISO 8601) ОписаниеСрок действия ссылки с учётом срока родителя

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

Получен живым локальным HTTP-вызовом; домен размещения и секрет ссылки замаскирован.

JSON
{
  "success": true,
  "data": {
    "url": "https://app-example.vibecode.bitrix24.tech/widget/style.css?__resource=SIGNED_RESOURCE_JWT",
    "expiresAt": "2026-10-10T14:11:21.000Z"
  }
}

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

400 — передан нулевой ttlSeconds:

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_RESOURCE_REQUEST",
    "message": "Expected path and optional integer ttlSeconds; no extra fields."
  }
}

Ошибки

HTTP Код Действие
HTTP400 КодINVALID_RESOURCE_REQUEST ДействиеИсправьте тело, типы полей или срок
HTTP400 КодINVALID_RESOURCE_PATH ДействиеУкажите канонический ASCII-путь ресурса
HTTP400 КодWRONG_TOKEN_MODE ДействиеИспользуйте родительский api-bearer
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 КодKEY_BLOCKED ДействиеТекущий или записанный прежний издатель токена заблокирован
HTTP403 КодTOKEN_OWNER_MISMATCH ДействиеИспользуйте ключ, которому принадлежат родитель и сервер
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ДействиеКлюч только для чтения не может выполнить запись
HTTP403 КодINFRA_FORBIDDEN_FOR_COWORK_KEY ДействиеИспользуйте управляющий ключ вне Коворк/Код
HTTP403 КодPORTAL_COLLABORATOR_KEY_OUT_OF_SCOPE ДействиеКлюч команды разработки не может подписывать URL ресурсов
HTTP403 КодEXTERNAL_COLLABORATOR_KEY_OUT_OF_SCOPE ДействиеКлюч внешнего участника не может подписывать URL ресурсов
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 ДействиеРодительский токен не найден или портал сервера деактивирован
HTTP404 КодSERVER_NOT_FOUND ДействиеПроверьте ID сервера
HTTP410 КодALREADY_REVOKED ДействиеВыпустите новый одобренный родительский токен
HTTP410 КодTOKEN_EXPIRED ДействиеВыпустите новый одобренный родительский токен с действующим сроком
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 указывает отказавший уровень
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

При чтении ресурса изменённая, просроченная или отозванная ссылка, другой метод, query или путь дают 401 BH_RESOURCE_URL_INVALID. Подпись ресурса не принимается как Bearer или cookie-сессия. Если туннель приложения не подключён, шлюз возвращает нейтральный JSON 503 BH_RESOURCE_UNAVAILABLE: ссылка не пробуждает сервер и не раскрывает биллинговое состояние владельца. Общие ошибки — Ошибки.

Шлюз проверяет состояние родительского токена при каждом чтении ресурса. Сетевой отказ, таймаут или некорректный ответ проверки дают нейтральный 503 BH_RESOURCE_UNAVAILABLE, а подтверждённый отзыв — 401 BH_RESOURCE_URL_INVALID. Запрос отклоняется без перехода к браузерной сессии или публичному доступу.

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

Виджет Главной при PORTAL

  1. Создайте один родительский токен api-bearer с нужным сроком и одобрением аудитории.
  2. Подпишите пути стиля и каждой картинки/шрифта отдельно этой операцией.
  3. Передайте подписанный URL стиля в WIDGET_PARAMS.style при регистрации через landing.repowidget.register. В CSS url(...), HTML-картинках и превью укажите соответствующие подписанные URL.
  4. Заранее обновляйте ссылки и регистрацию виджета до expiresAt. Относительный путь картинки не наследует подпись URL стиля и останется закрытым.
  5. Для досрочного закрытия всех ссылок отзовите родительский токен.

Обычные URL приложения при PORTAL остаются защищёнными. Шлюз не меняет HTML/CSS и не подписывает зависимости автоматически. Запрос ресурса не создаёт cookie, не передаёт пользовательскую личность и X-Vibe-Authorization; приложение должно обслуживать этот ресурс без персональной сессии. Ответы имеют Cache-Control: no-store и Referrer-Policy: no-referrer.

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