Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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-вызовом; домен размещения и секрет ссылки замаскирован.
{
"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:
{
"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
- Создайте один родительский токен
api-bearerс нужным сроком и одобрением аудитории. - Подпишите пути стиля и каждой картинки/шрифта отдельно этой операцией.
- Передайте подписанный URL стиля в
WIDGET_PARAMS.styleпри регистрации черезlanding.repowidget.register. В CSSurl(...), HTML-картинках и превью укажите соответствующие подписанные URL. - Заранее обновляйте ссылки и регистрацию виджета до
expiresAt. Относительный путь картинки не наследует подпись URL стиля и останется закрытым. - Для досрочного закрытия всех ссылок отзовите родительский токен.
Обычные URL приложения при PORTAL остаются защищёнными. Шлюз не меняет HTML/CSS и не подписывает зависимости автоматически. Запрос ресурса не создаёт cookie, не передаёт пользовательскую личность и X-Vibe-Authorization; приложение должно обслуживать этот ресурс без персональной сессии. Ответы имеют Cache-Control: no-store и Referrer-Policy: no-referrer.