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

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

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

#Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID BLACKHOLE-сервера

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

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

#Примеры

#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": "share-url",
    "ttlSeconds": 2592000,
    "identityBound": false,
    "name": "предпросмотр"
  }'

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

javascript 
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({ mode: 'api-bearer', ttlSeconds: 600 }),
  }
)
const { data } = await res.json()

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

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

javascript 
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({
      mode: 'share-url',
      ttlSeconds: 2592000,
      name: 'предпросмотр',
    }),
  }
)
const { data } = await res.json()
console.log(data.url) // https://app-xxxx.vibecode.bitrix24.tech/?s=R8k3Zm2P

#Поля ответа

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

Режим api-bearer:

Поле Тип Описание
success boolean Всегда true при успехе
data.id string ID токена для последующего отзыва
data.mode string "api-bearer"
data.token string JWT для заголовка Authorization: Bearer. Возвращается один раз — при выпуске
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": "tk_7d3fa2b1",
    "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. Bearer stops working at jwtExpiresAt. POST /access-tokens again to mint a fresh JWT."
  }
}

Режим share-url:

JSON 
{
  "success": true,
  "data": {
    "id": "tk_8e4gb3c2",
    "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 Код Описание
400 INVALID_MODE Передан недопустимый mode
400 INVALID_TTL ttlSeconds вне допустимого диапазона [300, 315 360 000]
400 NAME_TOO_LONG name превышает 100 символов
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
403 TOKEN_OWNER_MISMATCH Сервер принадлежит другому API-ключу
404 SERVER_NOT_FOUND Сервер не найден или удалён
409 ACTIVE_TOKEN_LIMIT Достигнут лимит 100 активных токенов на сервер
429 TOKEN_MINT_RATE_LIMIT Превышен лимит 50 выпусков в час на API-ключ. Заголовок Retry-After: 3600
503 FEATURE_DISABLED Токены доступа отключены на платформе

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

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

  • token действителен 10 минут независимо от ttlSeconds. Сохраните token и jwtExpiresAt сразу: JWT перестаёт работать по истечении jwtExpiresAt, а не expiresAt. expiresAt — срок хранения записи (для листинга и отзыва). Повторно получить JWT невозможно — выпустите новый токен через POST /access-tokens.
  • identityBound игнорируется для api-bearer. Идентификатором в журнале всегда выступает UUID владельца API-ключа.
  • Лимиты: 100 активных токенов на сервер; 50 выпусков в час на API-ключ; ttlSeconds от 300 до 315 360 000.

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