Вход в приложение из десктопа

POST /v1/cowork/app-login

Выдаёт десктопу Cowork/Code адрес задеплоенного приложения со ссылкой для входа, чтобы встроенный браузер открыл приложение сразу от имени владельца ключа, без формы авторизации.

Платформа сама решает, пускать ли человека: приложение должно принадлежать аккаунту Битрикс24, к которому привязан ключ, а его политика доступа должна пускать владельца ключа. Шлюз меняет токен из адреса на свою куку поддомена приложения и перенаправляет на адрес без токена. Приложение получает номер пользователя в Битрикс24, как при обычном входе. Токен открывает только это приложение — ни кабинет платформы, ни соседние приложения по нему не открываются.

Вызвать эндпоинт может только ключ десктопа Cowork/Code со скоупом vibe:cowork. Ключ агентского места и ключ стороннего агента несут тот же скоуп, но получают 403 COWORK_DESKTOP_KEY_REQUIRED.

Скоуп: vibe:cowork. Ключ должен относиться к классу десктопа Cowork/Code.

Поля запроса (body)

Примеры

curl

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

JavaScript — получить адрес входа и проверить его

// Адрес приложения: https, поддомен app-* домена приложений, без порта, данных пользователя и токена
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\.tech$/.test(u.hostname)
  } catch {
    return false
  }
}

async function getAppLoginUrl(appUrl) {
  // Не адрес приложения — ручку не зовём и адрес не открываем
  if (!isAppAddress(appUrl)) return null
  const res = await fetch('https://vibecode.bitrix24.tech/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(() => ({}))
    // Платформа не признала адрес приложением — не открываем его совсем
    if (error?.code === 'INVALID_APP_URL') return null
    return appUrl // прочие отказы — адрес уже проверен выше, открываем его с обычным входом
  }

  const { url } = await res.json() // { url, expiresIn } — без обёртки success/data
  // Ответ отличается от запроса ровно одним параметром токена
  const stripped = url.replace(/[?&]__gw_token=[^&#]*/, '')
  return stripped === appUrl ? url : null // расхождение — не открываем ничего
}

Поля ответа

Пример ответа

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

Пример ответа при ошибке

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

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

Успешный ответ (200) — это сам объект, без обёртки success. Ошибки приходят в конверте { success: false, error: { code, message } }. Определяйте успех по HTTP-статусу (res.ok).

Адрес ответа совпадает с запросом побайтно, кроме параметра токена. Платформа не пересобирает адрес: кодировка параметров, пустые значения и якорь остаются как в appUrl. Сравнивайте ответ с запросом после удаления параметра __gw_token и не открывайте адрес, если осталось расхождение. После обмена токена на куку шлюз перенаправляет на адрес без токена и собирает строку запроса заново: порядок параметров и запись пустых значений у приложения могут отличаться от appUrl.

Токен действует до конца срока, а не один раз. Повторный переход по тому же адресу в пределах expiresIn снова пускает в приложение. После первого перехода шлюз ставит куку и перенаправляет на адрес без токена, поэтому следующие открытия того же приложения идут по куке, без нового вызова.

Отзыв ключа останавливает выдачу новых входов. Кука, которую шлюз уже поставил, живёт свой срок. Политику доступа приложения шлюз перепроверяет сам, поэтому закрытие доступа к приложению действует и для такой куки.

Как реагировать на отказы. После 400 INVALID_APP_URL адрес не открывайте совсем: платформа не признала его адресом приложения, покажите пользователю ошибку. Любой другой отказ означает, что приложение нужно открыть по исходному адресу с обычным входом — но только если адрес прошёл вашу собственную проверку до запроса: https, поддомен вида app-* домена приложений, без порта, данных пользователя и параметра __gw_token. Отказ 401 или 403 приходит до разбора адреса и не подтверждает, что это адрес приложения. 401 — попросите пользователя войти в десктоп заново. 400 и 403 — ошибка клиента, повторять запрос бессмысленно. 429 — повторяйте с растущей паузой.

Смотрите также

• Cowork/Code
• Отключить это устройство
• Ошибки