لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/infra/access-tokens.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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.

Scope: vibe:infra

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.

Parameters

Parameter In Type Required Description
Parameterid Inpath Typestring (UUID) Requiredyes DescriptionBLACKHOLE server ID. List: GET /v1/infra/servers

Request body fields

Field Type Required Default Description
Fieldmode Typestring Requiredyes Default— Description"api-bearer" or "share-url"
FieldttlSeconds Typenumber Requiredno Default86400 DescriptionToken lifetime in seconds. Range: 300–315,360,000 (from 5 minutes to 10 years). The value 315,360,000 is shown in the Vibecode dashboard as "No expiration"
FieldidentityBound Typeboolean Requiredno Defaulttrue DescriptionFor share-url only. When true, login via Bitrix24 is required and the real user identifier is recorded in the log. When false, the visit is anonymous and a synthetic identifier is recorded
Fieldname Typestring Requiredno Default— DescriptionToken label for display in the list (up to 100 characters)

Examples

curl — personal key

Terminal 
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

Terminal 
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": "share-url",
    "ttlSeconds": 2592000,
    "identityBound": false,
    "name": "preview"
  }'

JavaScript — personal key

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

// 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

javascript 
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({
      mode: 'share-url',
      ttlSeconds: 2592000,
      name: 'preview',
    }),
  }
)
const { data } = await res.json()
console.log(data.url) // https://app-xxxx.vibecode.bitrix24.com/?s=R8k3Zm2P

Response fields

The set of fields depends on the mode.

api-bearer mode:

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionToken ID for later revocation
Fielddata.mode Typestring Description"api-bearer"
Fielddata.token Typestring DescriptionJWT for the Authorization: Bearer header. Save it right away: this exact string is not returned again, and a fresh JWT for the same record comes from token refresh
Fielddata.expiresAt Typestring (ISO 8601) DescriptionRetention period of the token record — for listing and revocation
Fielddata.jwtExpiresAt Typestring (ISO 8601) DescriptionThe actual expiry of the Bearer token. Capped at 10 minutes regardless of ttlSeconds. After it expires, mint a new token
Fielddata.note Typestring DescriptionNote about the difference between expiresAt and jwtExpiresAt
Fielddata.subdomain Typestring DescriptionServer subdomain
Fielddata.appUrl Typestring DescriptionFull HTTPS address of the application
Fielddata.curlExample Typestring DescriptionReady-to-use curl example with the token for a quick check

share-url mode:

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typestring DescriptionToken ID for later revocation
Fielddata.mode Typestring Description"share-url"
Fielddata.shortcode Typestring DescriptionCode inserted into the URL as ?s=<shortcode>
Fielddata.url Typestring DescriptionThe full shareable link
Fielddata.identityBound Typeboolean DescriptionWhether a visit requires login via Bitrix24
Fielddata.expiresAt Typestring (ISO 8601) DescriptionToken expiration time
Fielddata.name Typestring | null DescriptionThe label passed at mint time

Response example

api-bearer mode:

JSON 
{
  "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:

JSON 
{
  "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 and is not divided across replicas, so the number in the response is exact:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_MODE DescriptionAn invalid mode was passed, or a field in the body has the wrong value type
HTTP400 CodeUNKNOWN_PARAM DescriptionThe request body contains an unknown field. The response contains details with the list of valid fields and a suggestion
HTTP400 CodeINVALID_TTL DescriptionttlSeconds is outside the allowed range [300, 315,360,000]
HTTP400 CodeNAME_TOO_LONG Descriptionname exceeds 100 characters
HTTP400 CodeSERVER_NO_SUBDOMAIN DescriptionThe server has no subdomain, so there is nothing to send requests to
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not provided
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP403 CodeTOKEN_OWNER_MISMATCH DescriptionThe server belongs to a different API key. Being on the server's development team does not grant access to this operation — it requires the managing key regardless of your role.
HTTP403 CodeSERVER_KEY_MISMATCH DescriptionWhile the token was being issued, the server moved to another API key — for example, during a key rotation — or was deleted. No token was issued. Re-read the server with GET /v1/infra/servers/:id and issue the token with the key that owns the server now. If the server was deleted, that request answers 404
HTTP403 CodeAGENT_OWNER_ONLY DescriptionThe server was created for an AI agent — access tokens are disabled for it
HTTP403 CodeINFRA_FORBIDDEN_FOR_COWORK_KEY DescriptionThe 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
HTTP404 CodeSERVER_NOT_FOUND DescriptionServer not found or deleted
HTTP409 CodeACTIVE_TOKEN_LIMIT DescriptionThe limit of 100 active tokens per server has been reached
HTTP409 CodeKEY_ROTATION_RECOVERY_REQUIRED DescriptionThe replacement of the API key that made the request is unfinished: its rotation ended with a 500 response or has not finished yet. No token was issued. The steps are in Management keys, in the key rotation section
HTTP429 CodeTOKEN_MINT_RATE_LIMIT DescriptionThe limit of 50 mints per hour per API key has been exceeded. The count is kept in the database and is not divided across replicas. Header Retry-After: 3600
HTTP503 CodeFEATURE_DISABLED DescriptionThe 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.

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.
  • Extending access is cheaper than minting again. Token refresh issues a fresh JWT for the same record and consumes 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