Sign in to an app from the desktop

POST /v1/cowork/app-login

Gives the Cowork/Code desktop app a sign-in link to a deployed app, so the built-in browser opens the app already signed in as the key owner, without a sign-in form.

The platform decides access itself: the app must belong to the Bitrix24 account the key is bound to, and the app's access policy must admit the key owner. The gateway exchanges the token in the address for its own cookie on the app subdomain and redirects to the address without the token. The app receives the user's Bitrix24 ID, as with a regular sign-in. The token opens only this app: it opens neither the platform dashboard nor other apps.

A sign-in link is issued for an app on a dedicated server and for a Galaxy app: both go through the same access check. The shared galaxy host is not an app, and a request with its address gets 404 APP_NOT_AVAILABLE.

Only a Cowork/Code desktop key with the vibe:cowork scope can call this endpoint. Agent seat keys and third-party agent keys carry the same scope but receive 403 COWORK_DESKTOP_KEY_REQUIRED.

Scope: vibe:cowork. The key must also be a Cowork/Code desktop key.

Request fields (body)

Examples

curl

curl -X POST https://vibecode.bitrix24.com/v1/cowork/app-login \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"appUrl": "https://app-3f9c2a1b7e.vibecode.bitrix24.com/orders?status=new"}'

JavaScript — get the sign-in address and check it

// An app address: https, an app-* subdomain of the app domain, no port, user info, or gateway token
function isAppAddress(appUrl) {
  try {
    const u = new URL(appUrl)
    return u.protocol === 'https:' && !u.port && !u.username && !u.password
      && !u.searchParams.has('__gw_token')
      && /^app-[a-z0-9-]+\.vibecode\.bitrix24\.com$/.test(u.hostname)
  } catch {
    return false
  }
}

async function getAppLoginUrl(appUrl) {
  // Not an app address: do not call the endpoint and do not open the address
  if (!isAppAddress(appUrl)) return null
  const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/app-login', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_COWORK_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ appUrl }),
  })
  if (!res.ok) {
    const { error } = await res.json().catch(() => ({}))
    // The platform did not recognize the address as an app: do not open it at all
    if (error?.code === 'INVALID_APP_URL') return null
    return appUrl // any other refusal: the address was checked above, open it with the regular sign-in
  }

  const { url } = await res.json() // { url, expiresIn } — no success/data wrapper
  // The response differs from the request by exactly one token parameter
  const stripped = url.replace(/[?&]__gw_token=[^&#]*/, '')
  return stripped === appUrl ? url : null // a difference remains: open nothing
}

Response fields

Response example

{
  "url": "https://app-3f9c2a1b7e.vibecode.bitrix24.com/orders?status=new&__gw_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXAiOiJndyJ9.c2lnbmF0dXJl",
  "expiresIn": 600
}

Error response example

404 — the app is not available:

{
  "success": false,
  "error": {
    "code": "APP_NOT_AVAILABLE",
    "message": "The app is not available."
  }
}

Errors

Full list of common API errors: Errors.

Known specifics

A successful response (200) is the object itself, with no success wrapper. Errors come in the { success: false, error: { code, message } } envelope. Determine success by the HTTP status (res.ok).

The response address matches the request byte for byte, except for the token parameter. The platform does not rebuild the address: parameter encoding, empty values and the fragment stay as they are in appUrl. Compare the response with the request after removing the __gw_token parameter, and do not open the address if any difference remains. After exchanging the token for a cookie, the gateway redirects to the address without the token and rebuilds the query string, so the parameter order and the way empty values are written may differ from appUrl by the time the app receives it.

The token stays valid until it expires, not for a single use. Following the same address again within expiresIn signs the user in to the app again. After the first visit, the gateway sets a cookie and redirects to the address without the token, so later visits to the same app use the cookie, with no new call.

Revoking the key stops new sign-ins from being issued. A cookie the gateway has already set lives out its lifetime. The gateway rechecks the app's access policy itself, so revoking access to the app also applies to such a cookie.

How to react to refusals. After 400 INVALID_APP_URL do not open the address at all: the platform did not recognize it as an app address, so show the user an error. Any other refusal means the app should be opened at the original address with the regular sign-in, but only if the address passed your own check before the request: https, an app-* subdomain of the app domain, no port, user info, or __gw_token parameter. A 401 or 403 arrives before the address is parsed and does not confirm that it is an app address. 401: ask the user to sign in to the desktop app again. 400 and 403: a client error, so retrying is pointless. 429: retry with a growing delay.

See also

• Cowork/Code
• Sign this device out
• Errors