Endpoints

The server plugin exposes these endpoints under endpointPrefix. The default prefix is /cross-device.

Start

Creates the order on the initiating device.

await authClient.crossDevice.start({
  kind: "login",
  adapterId: "passkey",
  returnTo: "/dashboard",
  displayTitle: "Sign in",
  displaySummary: "Approve this sign-in on your phone.",
})

Returns:

Claim

Exchanges the claim token for a challenge token on the approving device.

await authClient.crossDevice.claim({
  orderId,
  claimToken,
})

Returns challengeToken.

Challenge

Reads the challenge envelope that your adapter prepared.

const challenge = await authClient.crossDevice.challenge({
  orderId,
  challengeToken,
})

The response includes action, nonce, origin, expiresAt, display text, adapter metadata, and the adapter-generated message.

Approve

Submits the adapter proof.

await authClient.crossDevice.approve({
  orderId,
  challengeToken,
  proof,
})

Returns { ok: true, orderId, status: "approved" }.

Reject

Rejects the order from the approving device.

await authClient.crossDevice.reject({
  orderId,
  challengeToken,
})

Returns { ok: true, orderId, status: "rejected" }.

Cancel

Cancels the order from the initiating device.

await authClient.crossDevice.cancel({
  orderId,
  desktopToken,
})

Returns { ok: true, orderId, status: "cancelled" }.

Finalize

Consumes an approved order from the initiating device.

await authClient.crossDevice.finalize({
  orderId,
  desktopToken,
})

For login orders, finalization applies the resolved Better Auth session and may return a token. For sign and transaction orders, finalization returns the approved proofArtifact.

Events

Subscribes to server-sent events for the initiating device.

const source = authClient.crossDevice.subscribe({
  orderId,
  eventToken,
  onEvent(event, payload) {
    console.log(event, payload.status)
  },
})

Events: claimed, waiting_user, approved, rejected, expired, cancelled, finalized.

Errors

Client helpers return { data, error }. Endpoint errors include a message and may include a Better Auth status code.