Signed resource URL

POST /v1/infra/servers/:id/access-tokens/:tokenId/resource-url

Issues a GET/HEAD URL for one resource of a private application: CSS, an image or a font. It works without a browser Gateway session and does not open other application paths. Anyone possessing the URL can read the selected resource until expiry or parent token revocation. Sign only content you intend to distribute to widget recipients.

Requires the key that manages the server and an existing api-bearer token created by that key through Mint a token, including the required audience approval. No new token record is created; the parent's lifetime and approved audience are not extended. Development-team, external-collaborator and Cowork keys cannot call this operation. Check section availability before calling.

Known link-preview fetchers receive a local card for a public application or a neutral page for a private application; the Gateway does not proxy their request through the tunnel even when it carries a resource URL. A resource URL does not override this policy.

Parameters

Request body

Extra body fields are rejected with 400 INVALID_RESOURCE_REQUEST.

Examples

Run on your application server. Do not send the key or user session to the browser.

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/resource-url" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/widget/style.css","ttlSeconds":86400}'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/resource-url" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"/widget/style.css","ttlSeconds":86400}'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/resource-url', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ path: '/widget/style.css', ttlSeconds: 86400 }),
})
const result = await res.json()
if (!res.ok || result.success !== true) {
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result
// Use data.url in the widget and replace it before data.expiresAt.

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/access-tokens/TOKEN_ID/resource-url', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    Authorization: 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ path: '/widget/style.css', ttlSeconds: 86400 }),
})
const result = await res.json()
if (!res.ok || result.success !== true) {
  throw new Error(result.error?.code ?? `HTTP_${res.status}`)
}
const { data } = result
// Use data.url in the widget and replace it before data.expiresAt.

Response fields

Response example

Captured from a local HTTP call; the deployment hostname and credential are masked.

{
  "success": true,
  "data": {
    "url": "https://app-example.vibecode.bitrix24.com/widget/style.css?__resource=SIGNED_RESOURCE_JWT",
    "expiresAt": "2026-10-10T14:11:21.000Z"
  }
}

Error response example

400 — ttlSeconds is zero:

{
  "success": false,
  "error": {
    "code": "INVALID_RESOURCE_REQUEST",
    "message": "Expected path and optional integer ttlSeconds; no extra fields."
  }
}

Errors

When reading a resource, an altered, expired or revoked URL, another method, query or path returns 401 BH_RESOURCE_URL_INVALID. Resource signatures are not accepted as Bearer or cookie sessions. If the application tunnel is disconnected, the Gateway returns neutral JSON 503 BH_RESOURCE_UNAVAILABLE: the URL does not wake the server or expose the owner's billing state. Common errors: Errors.

The Gateway checks the parent token on every resource read. A network failure, timeout or malformed authority response returns neutral 503 BH_RESOURCE_UNAVAILABLE; confirmed revocation returns 401 BH_RESOURCE_URL_INVALID. The request is refused without falling back to a browser session or public access.

Known specifics

Main-page widget with PORTAL access

1. Create one parent api-bearer token with the required lifetime and audience approval.
2. Sign the stylesheet and each image/font path separately through this operation.
3. Use the signed stylesheet URL as WIDGET_PARAMS.style when registering through landing.repowidget.register. Use the corresponding signed URLs in CSS url(...), HTML images and previews.
4. Renew the URLs and update widget registration before expiresAt. Relative image paths do not inherit the stylesheet URL's signature and remain private.
5. Revoke the parent to stop every derived URL early.

Ordinary application URLs remain protected under PORTAL. The Gateway does not rewrite HTML/CSS or automatically sign dependencies. Resource requests do not create cookies or forward user identity or X-Vibe-Authorization; the application must serve the resource without a personal session. Responses carry Cache-Control: no-store and Referrer-Policy: no-referrer.

See also

• Mint a token
• Revoke a token
• What the app receives