Обновить токен доступа

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

Выпускает свежий JWT для уже существующего токена режима api-bearer — без создания новой записи. JWT действует до 10 минут (или до expiresAt записи, если он ближе). Долгоживущему клиенту (CI, AI-агент) удобнее вызывать обновление перед истечением jwtExpiresAt, чем выпускать новый токен: обновление не расходует лимит активных токенов и лимит выпусков в час.

Тело запроса не требуется.

Параметры

Параметр В Тип Обяз. Описание
id path string (UUID) да ID BLACKHOLE-сервера
tokenId path string (UUID) да ID токена api-bearer (поле data.id из ответа на выпуск)

Примеры

curl

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/refresh" \
  -H "X-Api-Key: YOUR_API_KEY"

JavaScript — цикл «использовал → при 401 обновил → повторил»

javascript 
async function callWithRefresh(serverId, tokenId, appUrl, jwt) {
  let res = await fetch(`${appUrl}/api/health`, {
    headers: { Authorization: `Bearer ${jwt}` },
  })
  if (res.status === 401) {
    const r = await fetch(
      `https://vibecode.bitrix24.tech/v1/infra/servers/${serverId}/access-tokens/${tokenId}/refresh`,
      { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY' } },
    )
    const { data } = await r.json()
    jwt = data.token // тот же tokenId, свежий JWT
    res = await fetch(`${appUrl}/api/health`, {
      headers: { Authorization: `Bearer ${jwt}` },
    })
  }
  return res
}

Поля ответа

Поле Тип Описание
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) Реальный срок действия нового JWT. Ограничен 10 минутами (или expiresAt записи, если он ближе)
data.subdomain string Субдомен сервера
data.appUrl string Полный HTTPS-адрес приложения
data.curlExample string Готовый curl-пример с новым токеном
data.note string Пояснение о сроках действия и о повторном вызове

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

JSON 
{
  "success": true,
  "data": {
    "id": "tk_7d3fa2b1",
    "mode": "api-bearer",
    "token": "eyJhbGciOiJFUzI1NiJ9...",
    "expiresAt": "2026-06-25T10:50:00.000Z",
    "jwtExpiresAt": "2026-06-25T10: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": "Refreshed the Gateway session JWT for this api-bearer token (same token id, no new row)."
  }
}

Ошибки

HTTP Код Описание
400 WRONG_TOKEN_MODE Токен в режиме share-url. Обновление применимо только к api-bearer; ссылки share-url обновляются сами при переходе
400 SERVER_NO_SUBDOMAIN У сервера нет субдомена
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный или просроченный API-ключ
403 TOKEN_OWNER_MISMATCH Токен принадлежит другому ключу либо сервер больше не привязан к вашему ключу
404 NOT_FOUND Токен не найден на этом сервере
404 SERVER_NOT_FOUND Сервер не найден или удалён
410 ALREADY_REVOKED Токен отозван — выпустите новый
410 TOKEN_EXPIRED Срок хранения записи истёк — выпустите новый токен через POST /access-tokens
503 FEATURE_DISABLED Токены доступа отключены на платформе

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

Диагностика отказа Gateway

Если запрос к приложению с заголовком Authorization: Bearer возвращает 401 с кодом BH_LOGIN_REQUIRED, тело ответа содержит поле reason с конкретной причиной отказа Gateway:

reason Что произошло Что делать
expired JWT просрочен (истёк 10-минутный срок) Обновите токен этим эндпоинтом или выпустите новый
signature Подпись не сошлась Используйте токен, выпущенный для этого сервера; не редактируйте его
subdomain Токен привязан к другому субдомену Обращайтесь к собственному субдомену app-* сервера
revoked Токен отозван Выпустите новый токен
type Передан не api-bearer-токен Используйте токен режима api-bearer, а не cookie-сессию
malformed / invalid Строка не является корректным JWT Проверьте целостность токена

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

  • Обновление не создаёт новую запись. data.id остаётся прежним; запись токена и её expiresAt не меняются — обновляется только JWT. Один отзыв (DELETE) гасит и исходный, и все обновлённые JWT одного токена.
  • JWT никогда не живёт дольше записи. Если до expiresAt записи осталось меньше 10 минут, новый jwtExpiresAt обрезается до этого срока.
  • Только для api-bearer. Ссылки share-url обновляются автоматически при каждом переходе через /auth/bh-login.

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