Билет для телефонного доступа

POST /v1/cowork/relay-ticket

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

Билет действует 5 минут и привязан к публичному ключу десктопа из тела запроса: с другим ключом ретранслятор его не примет. Держите билет в памяти и используйте его для переподключений, пока до expiresAt остаётся больше 60 секунд. Когда до expiresAt остаётся 60 секунд или меньше, при следующем подключении запросите новый билет.

Скоуп: vibe:cowork плюс класс ключа десктопа Cowork/Code. У владельца ключа должно быть активное место Cowork/Code.

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

Примеры

Эндпоинт принимает только ключ десктопа Cowork/Code, поэтому примеров два.

curl — ключ десктопа Cowork/Code

curl -X POST https://vibecode.bitrix24.tech/v1/cowork/relay-ticket \
  -H "X-Api-Key: YOUR_COWORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pubkey": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"}'

JavaScript — ключ десктопа Cowork/Code

let cached = null

async function getRelayTicket(pubkey) {
  // Переиспользуем билет, пока до истечения больше 60 секунд
  if (cached && Date.parse(cached.expiresAt) - Date.now() > 60_000) {
    return cached.ticket
  }

  const res = await fetch('https://vibecode.bitrix24.tech/v1/cowork/relay-ticket', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_COWORK_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ pubkey }),
  })
  if (!res.ok) {
    const { error } = await res.json()
    throw new Error(`${res.status} ${error.code}`)
  }

  cached = await res.json() // { ticket, expiresAt } — без обёртки success/data
  return cached.ticket
}

Поля ответа

Для справки: заголовок билета несёт alg: "EdDSA", typ: "JWT" и kid ключа подписи. В полезной нагрузке лежат typ: "cowork-relay-ticket", iss: "vibecode-platform", aud: "cowork-relay", sub и portal, cnf.jwk, в поле x которого лежит переданный pubkey, а также jti, iat и exp. Поля sub и portal — псевдонимы: ретранслятор различает по ним пользователей и аккаунты, но настоящих идентификаторов не узнаёт.

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

Значение ticket сокращено:

{
  "ticket": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9.eyJ0eXAiOiJjb3dvcmstcmVsYXktdGlja2V0Ii4uLn0.c2lnbmF0dXJl",
  "expiresAt": "2026-09-22T12:05:00.000Z"
}

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

403 — ключ со скоупом vibe:cowork, но не от десктопа Cowork/Code:

{
  "success": false,
  "error": {
    "code": "COWORK_DESKTOP_KEY_REQUIRED",
    "message": "Only a Cowork/Code desktop key may request a relay ticket."
  }
}

Ошибки

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

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

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

Билет не сохраняется на платформе. Каждый вызов выдаёт новый билет, а прежние действуют до своего expiresAt. Отозвать выданный билет нельзя.

Эндпоинт сначала проверяет, доступна ли выдача билетов, и только потом — тело запроса. Пока выдача билетов недоступна, эндпоинт отвечает 503 COWORK_RELAY_NOT_CONFIGURED даже на запрос с неверным pubkey.

Как реагировать на отказы.

• 401 — попросите пользователя войти заново.
• 400, 403 INSUFFICIENT_SCOPE и 403 COWORK_DESKTOP_KEY_REQUIRED — повтор вернёт тот же отказ, исправьте запрос или ключ.
• 404 COWORK_NOT_ACTIVATED и 403 COWORK_SEAT_INACTIVE — пользователю нужно активное место Cowork/Code.
• 503 — состояние платформы, а не проблема ключа: повторите позже.
• 429 — повторяйте с растущей паузой.

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

• Cowork/Code
• Состояние подписки Cowork/Code
• Отключить это устройство
• Ошибки