For AI agents: markdown of this page — /docs-content-en/infra/access-tokens/refresh.md documentation index — /llms.txt

Refresh an access token

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

Mints a fresh JWT for an existing api-bearer token — without creating a new record. A long-running client (CI, AI agent) calls refresh before jwtExpiresAt is reached instead of minting a new token: refresh counts against neither the active-token limit nor the hourly mint limit.

No request body is required.

Parameters

Parameter In Type Required Description
id path string (UUID) yes BLACKHOLE server ID. List: GET /v1/infra/servers
tokenId path string (UUID) yes api-bearer token ID — the data.id field from a mint response or an item from the token list

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/refresh" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-tokens/${tokenId}/refresh`,
  {
    method: 'POST',
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  }
)
const { data } = await res.json()
console.log(data.token, data.jwtExpiresAt)

JavaScript — OAuth application

javascript 
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-tokens/${tokenId}/refresh`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)
const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data.id string Token ID — the same as at mint time (no new record is created)
data.mode string "api-bearer"
data.token string Fresh JWT for the Authorization: Bearer header
data.expiresAt string (ISO 8601) Retention period of the token record — unchanged by refresh
data.jwtExpiresAt string (ISO 8601) Actual expiry of the new JWT. Capped at 10 minutes (or the record's expiresAt, whichever is sooner)
data.subdomain string Server subdomain
data.appUrl string Full HTTPS address of the app
data.curlExample string Ready-to-use curl example with the new token
data.note string Note about the validity periods and when to call refresh again

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "9f1c4b7e-3d52-4a18-9c0e-7b2a1f6d84c3",
    "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.com",
    "curlExample": "curl -H \"Authorization: Bearer eyJhbGciOiJFUzI1NiJ9...\" https://app-91306a4c.vibecode.bitrix24.com/api/health",
    "note": "Refreshed the Gateway session JWT for this api-bearer token (same token id, no new row). The JWT is valid for up to 10 minutes (or until the row's expiresAt, whichever is sooner). Call this endpoint again before jwtExpiresAt to keep a long-running client authenticated."
  }
}

Error response example

410 — the record's retention period has elapsed:

JSON 
{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "The long-lived token row has expired; mint a new token."
  }
}

Errors

HTTP Code Description
400 WRONG_TOKEN_MODE The token is in share-url mode. Refresh applies only to api-bearer; share-url links auto-refresh on each visit
400 SERVER_NO_SUBDOMAIN The server has no subdomain
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY Invalid or expired API key
403 TOKEN_OWNER_MISMATCH The token belongs to a different key, or the server is no longer bound to your key
403 INFRA_FORBIDDEN_FOR_COWORK_KEY The call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see Project key for deploy
404 NOT_FOUND Token not found on this server
404 SERVER_NOT_FOUND Server not found or deleted
410 ALREADY_REVOKED The token was revoked — mint a new one
410 TOKEN_EXPIRED The record's retention period has expired — mint a new token via POST /access-tokens
503 FEATURE_DISABLED The access-tokens section is disabled on the platform. The pre-call signal and the fallback are described in Availability

Full list of common API errors — Errors.

Diagnosing a Gateway rejection

If a request to the app with the Authorization: Bearer header returns 401 with code BH_LOGIN_REQUIRED, the response body carries a reason field with the specific Gateway rejection cause:

reason What happened What to do
expired The JWT expired (the 10-minute window elapsed) Refresh the token via this endpoint, or mint a new one
signature The signature did not match Use a token minted for this server; do not edit it
subdomain The token is bound to a different subdomain Send the request to the server's own app-* subdomain
revoked The token was revoked Mint a new token
type A non-api-bearer token was sent Use an api-bearer token, not a cookie session
malformed / invalid The string is not a valid JWT Check that the token is intact

Known specifics

  • A single revocation invalidates every JWT issued for the token. A DELETE on the record stops both the original JWT and every JWT issued by refresh.
  • share-url links refresh themselves. Every visit goes through /auth/bh-login, so calling refresh for them is unnecessary.
  • A ready-made "use → on 401 refresh → retry" loop. Instead of watching a timer, the client reacts to a rejection:
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.com/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 // same tokenId, fresh JWT
    res = await fetch(`${appUrl}/api/health`, {
      headers: { Authorization: `Bearer ${jwt}` },
    })
  }
  return res
}

See also