Ticket for phone access

POST /v1/cowork/relay-ticket

Issues a signed ticket that the Cowork/Code desktop app uses to connect to the relay, the server through which a phone reaches the desktop. The platform only confirms who is connecting: no traffic passes through it, and the desktop is not registered as a server.

The ticket is valid for 5 minutes and is bound to the desktop public key from the request body: the relay rejects it if presented with any other key. Keep the ticket in memory and reuse it for reconnects while more than 60 seconds remain before expiresAt. Once 60 seconds or less remain before expiresAt, request a new ticket on the next connection.

Scope: vibe:cowork; the key must also be a Cowork/Code desktop key. The key owner must have an active Cowork/Code seat.

Request fields (body)

Examples

This endpoint accepts only a Cowork/Code desktop key, so there are two examples.

curl — Cowork/Code desktop key

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

JavaScript — Cowork/Code desktop key

let cached = null

async function getRelayTicket(pubkey) {
  // Reuse the ticket while more than 60 seconds remain until expiry
  if (cached && Date.parse(cached.expiresAt) - Date.now() > 60_000) {
    return cached.ticket
  }

  const res = await fetch('https://vibecode.bitrix24.com/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 } — no success/data wrapper
  return cached.ticket
}

Response fields

For reference: the ticket header carries alg: "EdDSA", typ: "JWT" and the kid of the signing key. The payload holds typ: "cowork-relay-ticket", iss: "vibecode-platform", aud: "cowork-relay", sub and portal, cnf.jwk, whose x field holds the pubkey you sent, as well as jti, iat and exp. The sub and portal fields hold pseudonyms: the relay can tell users and Bitrix24 accounts apart by them but does not learn the real identifiers.

Response example

The ticket value is truncated:

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

Error response example

403 — a key with the vibe:cowork scope that is not a Cowork/Code desktop key:

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

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 ticket is not stored on the platform. Each call issues a new ticket, and earlier ones stay valid until their expiresAt. An issued ticket cannot be revoked.

The endpoint checks whether ticket issuance is available before it validates the request body. While ticket issuance is unavailable, the endpoint returns 503 COWORK_RELAY_NOT_CONFIGURED even for a request with an invalid pubkey.

How to react to refusals.

• 401: ask the user to sign in again.
• 400, 403 INSUFFICIENT_SCOPE and 403 COWORK_DESKTOP_KEY_REQUIRED: a retry returns the same refusal, so fix the request or the key.
• 404 COWORK_NOT_ACTIVATED and 403 COWORK_SEAT_INACTIVE: the user needs an active Cowork/Code seat.
• 503: a platform state, not a problem with the key, so retry later.
• 429: retry with a growing delay.

See also

• Cowork/Code
• Cowork/Code subscription state
• Sign this device out
• Errors