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

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

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

Нужен ключ, управляющий сервером, и существующий токен `api-bearer`, созданный этим ключом через [выпуск токена](./create.md), с требуемым одобрением аудитории. Новая запись токена не создаётся; срок и одобренная аудитория родителя не расширяются. Ключи команды разработки, внешнего участника и Коворк/Код не могут вызывать эту операцию. Доступность раздела проверяйте [до вызова](/docs/infra/access-tokens#доступность).

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

## Параметры

| Параметр | Где | Тип | Обязателен | Описание |
|---|---|---|---|---|
| `id` | path | string | да | ID сервера из [списка серверов](/docs/infra/servers/list) |
| `tokenId` | path | string | да | `data.id` существующего [выпущенного токена `api-bearer`](./create.md) |

## Поля запроса (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 — личный ключ

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

```bash
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 | Код | Действие |
|---|---|---|
| 400 | `INVALID_RESOURCE_REQUEST` | Исправьте тело, типы полей или срок |
| 400 | `INVALID_RESOURCE_PATH` | Укажите канонический ASCII-путь ресурса |
| 400 | `WRONG_TOKEN_MODE` | Используйте родительский api-bearer |
| 400 | `SERVER_NO_SUBDOMAIN` | Используйте сервер с поддоменом |
| 401 | `MISSING_API_KEY` | Ключ не передан через `X-Api-Key` или поддерживаемую схему `Authorization: Bearer` |
| 401 | `INVALID_API_KEY` | Ключ авторизации не опознан |
| 401 | `KEY_INACTIVE` | Ключ, которым сделан запрос, больше не активен |
| 401 | `KEY_EXPIRED` | Истёк срок действия ключа API, которым сделан запрос; это не срок resource URL |
| 401 | `NO_PORTAL` | Ключ, не являющийся управляющим, не привязан к порталу |
| 401 | `COWORK_CHAT_KEY_INACTIVE` | Для ключа чата Коворк/Код родительский ключ устройства больше не пригоден |
| 401 | `WRONG_AUTH_SCHEME` | Ключ приложения OAuth передан как Bearer-сессия: передайте ключ в `X-Api-Key`, а сессию — в `Authorization: Bearer` |
| 401 | `INVALID_SESSION` | Переданная сессия OAuth недействительна или истекла |
| 401 | `TOKEN_EXPIRED` | Токен пользователя OAuth истёк, а его обновление не удалось; требуется повторная авторизация |
| 401 | `TOKEN_INVALID` | При включённом партнёрском контуре AI передан неизвестный или истёкший токен этого контура |
| 401 | `KEY_REVOKED` | Партнёрский ключ, связанный с токеном контура AI, отозван |
| 402 | `ACCOUNT_FROZEN` | Счёт владельца ключа заморожен. При выключенной развязке долга общий гард API-ключа отказывает до обработчика. Для восстановления баланса используйте error.topupUrl; сам статус не разрешает повтор предыдущей записи |
| 403 | `KEY_BLOCKED` | Текущий или записанный прежний издатель токена заблокирован |
| 403 | `TOKEN_OWNER_MISMATCH` | Используйте ключ, которому принадлежат родитель и сервер |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения не может выполнить запись |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | Используйте управляющий ключ вне Коворк/Код |
| 403 | `PORTAL_COLLABORATOR_KEY_OUT_OF_SCOPE` | Ключ команды разработки не может подписывать URL ресурсов |
| 403 | `EXTERNAL_COLLABORATOR_KEY_OUT_OF_SCOPE` | Ключ внешнего участника не может подписывать URL ресурсов |
| 403 | `IP_NOT_ALLOWED` | IP вызывающего не входит в разрешённый список ключа |
| 403 | `OWNER_BLOCKED` | Владелец ключа заблокирован |
| 403 | `OWNER_DELETED` | Владелец ключа удалён |
| 403 | `PORTAL_SUSPENDED` | Привязанный портал Битрикс24 приостановлен |
| 403 | `PORTAL_DELETED` | Привязанный портал Битрикс24 удалён |
| 403 | `PORTAL_BLOCKED` | Привязанный портал Битрикс24 заблокирован |
| 403 | `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | У управляющего ключа нет необходимой привязки к порталу или прав доступа к его данным |
| 403 | `AGENT_MAINTENANCE_KEY_OUT_OF_SCOPE` | Вызов не входит в список маршрутов ключа обслуживания |
| 403 | `APP_API_KEY_OUT_OF_SCOPE` | Вызов не входит в список маршрутов ключа приложения |
| 403 | `WAITLIST_PENDING` | Владелец ключа ещё не активирован |
| 403 | `SESSION_APP_MISMATCH` | Сессия OAuth относится к другому приложению |
| 403 | `PLANE_FORBIDDEN` | Ключ партнёра не разрешает этот AI-контур |
| 403 | `SYSTEM_FORBIDDEN` | Ключ партнёра не разрешает эту AI-систему |
| 403 | `SCOPE_FORBIDDEN` | AI-контур партнёра запрещает этот маршрут |
| 403 | `CONNECT_COMPANY_DERIVED_TOKEN_FORBIDDEN` | Ключ подключения компании не может управлять производными токенами |
| 403 | `COWORK_READONLY` | Место Коворк/Код доступно только для чтения |
| 403 | `GALAXY_DISABLED` | Операции галактики выключены для этого портала |
| 404 | `NOT_FOUND` | Родительский токен не найден или портал сервера деактивирован |
| 404 | `SERVER_NOT_FOUND` | Проверьте ID сервера |
| 410 | `ALREADY_REVOKED` | Выпустите новый одобренный родительский токен |
| 410 | `TOKEN_EXPIRED` | Выпустите новый одобренный родительский токен с действующим сроком |
| 429 | `QUOTA_EXCEEDED` | Включён платный учёт API с ненулевой ценой превышения квоты: суточная бесплатная квота исчерпана, баланс PREPAY неположительный. Пополните баланс. `error.quota` и `error.used` содержат счётчики; `X-RateLimit-Quota`, `X-RateLimit-Used` и `X-RateLimit-Remaining` — квоту, расход и нулевой остаток. Этот отказ не гарантирует `Retry-After` или `X-RateLimit-Scope` |
| 429 | `CALLER_RATE_LIMITED` | Общий лимит запросов ключа или пользователя. Подождите число секунд из `Retry-After`; `X-RateLimit-Scope` указывает отказавший уровень |
| 503 | `FEATURE_DISABLED` | Раздел токенов доступа недоступен |
| 503 | `ACCOUNT_PENDING_ERASURE` | Владелец ключа ожидает удаления или уже удаляется. Заголовок `Retry-After: 3600` |
| 503 | `SERVICE_DISABLED` | AI-контур партнёра или сервис готовности его квоты выключен. Заголовок `Retry-After` для этого отказа не гарантирован |
| 503 | `user_self_deletion_pending` | Владелец API-ключа запланировал удаление. Проверка раздела токенов отказывает до обработчика. Заголовок `Retry-After: 604800` |

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

Шлюз проверяет состояние родительского токена при каждом чтении ресурса. Сетевой отказ, таймаут или некорректный ответ проверки дают нейтральный `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. Для досрочного закрытия всех ссылок отзовите [родительский токен](./delete.md).

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

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

- [Выпустить токен](./create.md)
- [Отозвать токен](./delete.md)
- [Что приходит в приложение](/docs/infra/app-runtime)
