Access tokens

Short-lived tokens for external access to a deployed application on a BLACKHOLE server. Two modes: api-bearer — JWT for the Authorization HTTP header, share-url — a distributable link with cookie authentication.

Mint an access token

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

Mints a short-lived token for external access to a deployed application. Two modes: api-bearer — a JWT for the Authorization HTTP header; share-url — a link that sets a cookie when visited.

A development-team key with the ADMIN or DEVELOPER role can mint only api-bearer. On the first request, supply ttlSeconds between 300 and 600. When retrying an approved operation, supply the exact expiresAt from retryOperation and the approved request ID as approvalId, without ttlSeconds. See Approving wider access for the approval flow.

Recovery depends on the calling key. After 410 TOKEN_EXPIRED, the token record may already exist even though no JWT was returned. Use the key that manages the server to list tokens with status=all before another mint. A development-team caller must ask that key holder to reconcile. Development-team keys cannot call refresh or mint share-url; further access requires a separately approved new api-bearer mint.

Parameters

Request body fields

Access approval

If minting expands access, the first request returns 409 AUDIENCE_APPROVAL_REQUIRED. Its error.details contains proposalId, approvalUrl, expiresAt and retryOperation. No token is minted at this step. Send the URL to a human authorized to approve access and signed in to their Vibecode account; an API key cannot approve its own request. Use the same key to read the request state. After APPROVED, start with the original HTTP body, remove ttlSeconds, and add only expiresAt from retryOperation and approvalId equal to proposalId. The retryOperation object is not an HTTP body: do not send its internal type or uppercase mode. Do not recalculate expiry or change mode, name or identity binding.

APPROVED means consent, not a minted token. If parameters or access changed, or approval was consumed or expired, branch on the error code in the table below. With 410 TOKEN_EXPIRED, a record may already exist but no JWT was returned: ask the holder of the key that manages the server to list and reconcile token records with status=all before retrying, and obtain separate approval for a further mint. A development-team key cannot list tokens.

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/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 application

curl -X POST "https://vibecode.bitrix24.com/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": "api-bearer",
    "ttlSeconds": 600,
    "name": "ci-smoke"
  }'

JavaScript — personal key

const requestBody = { mode: 'api-bearer', ttlSeconds: 600, name: 'ci-smoke' }
const res = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/access-tokens`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestBody),
  }
)
const result = await res.json()
if (!res.ok || result.success !== true) {
  if (res.status === 409 && result.error?.code === 'AUDIENCE_APPROVAL_REQUIRED') {
    const { proposalId, approvalUrl, retryOperation } = result.error.details
    const { ttlSeconds, ...sameIntent } = requestBody
    const retryBody = { ...sameIntent, expiresAt: retryOperation.expiresAt, approvalId: proposalId }
    // Send approvalUrl to a human; after APPROVED, submit retryBody with the same key.
    console.log({ proposalId, approvalUrl, retryBody })
    throw new Error('Access approval is pending')
  }
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result

// E2E check via the public path
const check = await fetch(`${data.appUrl}/api/health`, {
  headers: { Authorization: `Bearer ${data.token}` },
})
console.log(check.status) // 200 — the application responds through the Gateway

JavaScript — OAuth application

const requestBody = { mode: 'api-bearer', ttlSeconds: 600, name: 'ci-smoke' }
const res = await fetch(
  `https://vibecode.bitrix24.com/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(requestBody),
  }
)
const result = await res.json()
if (!res.ok || result.success !== true) {
  if (res.status === 409 && result.error?.code === 'AUDIENCE_APPROVAL_REQUIRED') {
    const { proposalId, approvalUrl, retryOperation } = result.error.details
    const { ttlSeconds, ...sameIntent } = requestBody
    const retryBody = { ...sameIntent, expiresAt: retryOperation.expiresAt, approvalId: proposalId }
    // Send approvalUrl to a human; after APPROVED, submit retryBody with the same key.
    console.log({ proposalId, approvalUrl, retryBody })
    throw new Error('Access approval is pending')
  }
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result

// E2E check via the public path
const check = await fetch(`${data.appUrl}/api/health`, {
  headers: { Authorization: `Bearer ${data.token}` },
})
console.log(check.status) // 200 — the application responds through the Gateway

Response fields

The set of fields depends on the mode.

api-bearer mode:

share-url mode:

Response example

api-bearer mode:

{
  "success": true,
  "data": {
    "id": "9f1c4b7e-3d52-4a18-9c0e-7b2a1f6d84c3",
    "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.com",
    "curlExample": "curl -H \"Authorization: Bearer eyJhbGciOiJFUzI1NiJ9...\" https://app-91306a4c.vibecode.bitrix24.com/api/health",
    "note": "JWT is a 10-minute Gateway session token. The row's `expiresAt` is the long-lived TTL for listing/revoking, but the Bearer token itself stops working at `jwtExpiresAt`. To keep a long-running client authenticated, POST /v1/infra/servers/:id/access-tokens/:tokenId/refresh before jwtExpiresAt to re-mint a fresh JWT for the SAME token (no new row — does not consume the active-token cap or mint rate-limit), or use mode=share-url for browser links that auto-refresh on each visit."
  }
}

share-url mode:

{
  "success": true,
  "data": {
    "id": "2a7d5e61-84bc-4f39-b0d7-5e6c9a3f1b28",
    "mode": "share-url",
    "shortcode": "R8k3Zm2P",
    "url": "https://app-91306a4c.vibecode.bitrix24.com/?s=R8k3Zm2P",
    "identityBound": false,
    "expiresAt": "2026-06-17T08:44:00.000Z",
    "name": "preview"
  }
}

Error response example

429 — token mint rate limit exceeded. The count is kept in the database, so the number in the response is exact:

{
  "success": false,
  "error": {
    "code": "TOKEN_MINT_RATE_LIMIT",
    "message": "Rate limit: 50 mints/hour per API key"
  }
}

Errors

For the full list of common API errors, see Errors.

Known specifics

• Minting a link is recorded in the Bitrix24 account's access log. A successful mint in share-url mode is logged when the server is bound to a Bitrix24 account, and does not depend on the account's settings. The administrator can read that log and receive notifications in accounts where the platform has enabled the "Applications" section: there the administrator sees that the application was opened via a link, and if the link does not require signing in to Bitrix24 (that is, identityBound is false) and the application had not previously been exposed externally, administrators additionally receive a chat-bot message with a link to the list of externally accessible applications. The request format, the response and the refusal codes do not change.
• For tokens issued by the key that manages the server, extending access is cheaper than minting again. Token refresh issues a fresh JWT for the same record and counts against neither the active-token cap nor the hourly mint limit.
• For api-bearer, the identifier in the log is always the same. It is the UUID of the API key owner. The identityBound field does not affect it and is returned as true in the list response.
• api-bearer confirms the request is made by the key owner, but does not create a Bitrix24 user session. The token authenticates the request as the API key owner and grants access to the application according to its access policy. It does not inject the X-Vibe-Authorization header and does not provide currentUser in the GET /v1/me response. Therefore an application route that verifies a Bitrix24 administrator via X-Vibe-Authorization and GET /v1/me will get currentUser: null under an api-bearer token. Such a route needs full user authorization through an OAuth application (placement) — see What the app receives.

See also

• Refresh a token
• List tokens
• Revoke a token
• Access tokens
• Deploy API