> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# showDeviceLinkQR()

> Reference for the Embedded API showDeviceLinkQR() method.

Use `showDeviceLinkQR()` to initiate device pairing for the Corti mobile companion app. The method opens a QR pairing screen that lives on a separate URL. How you surface this is up to you, but a common pattern is a "Pair mobile device" option in your application's settings that presents the URL in a modal or dedicated panel. The method resolves when the pairing request settles and returns the final status.

<Info>
  Applies to Web Component, Window API, and PostMessage. Examples on this page
  use the Web Component API shape.
</Info>

<Check>
  Enable the companion app surface with
  [`configureApp()`](/assistant/api/configure-app) before offering mobile
  pairing controls in your host application.
</Check>

<Info>
  QR code generation requires a **second** Keycloak token response for the same user — do not reuse the token from your original authentication request. Each application (desktop and companion) needs its own token so that both can refresh their sessions independently.
</Info>

## Usage

```ts title="TypeScript" theme={null}
// Ensure that you have authenticated your user with your chosen method
// and have obtained the required tokens

// Replace these with your values
const ACCESS_TOKEN = "<your-access-token>";
const REFRESH_TOKEN = "<your-refresh-token>";

await api.configureApp({
  companionApp: {
    enabled: true,
  },
});

// Generate the QR code for pairing the companion app
const result = await api.showDeviceLinkQR({
  access_token: ACCESS_TOKEN,
  refresh_token: REFRESH_TOKEN,
  token_type: "Bearer",
});

if (result.status === "approved") {
  // The mobile companion app was paired successfully.
}
```

## Prerequisites

* User must be authenticated in the Embedded Assistant.
* `companionApp.enabled` should be set to `true` in `configureApp()`.
* The payload must include a valid access token and refresh token for the same user session.

## Input validation

* `access_token`: Must be a valid OAuth access token.
* `refresh_token`: Must be present. The mobile companion app uses it to complete pairing after approval.
* `token_type`: Must match the OAuth token response, usually `"Bearer"`.

## Returns

```typescript theme={null}
type ShowDeviceLinkQRResponse = {
  status: "approved" | "denied" | "expired" | "dismissed";
};
```

* `approved`: The user approved the mobile device pairing request.
* `denied`: The user denied the mobile device pairing request.
* `expired`: The QR code or approval window expired before pairing completed.
* `dismissed`: A new QR request replaced the previous one, the embedded route was dismissed, or the pairing flow could not complete.

## Possible errors

* `UNAUTHORIZED`: User not authenticated.
* `INVALID_PAYLOAD`: Token payload is missing required values.
* `INTERNAL_ERROR`: Failed to create or display the pairing request.

## Companion app installation

The pairing page displays a QR code. Users scan it from the Corti Companion app or enter the code manually. A confirmation prompt then appears on the desktop showing the device name, so the user can approve or deny to make sure they are pairing the intended device. Once paired, the companion app must be open and running for the phone to appear as a selectable microphone source in the Embedded Assistant.

If you want to surface download links in your own application's help center or onboarding flow, the app is available on iOS and Android:

<div style={{ display: "flex", gap: "12px", alignItems: "center" }}>
  <a href="https://apps.apple.com/app/id6740490926" style={{ textDecoration: "none", borderBottom: "none", lineHeight: 0 }}>
    <img src="https://mintcdn.com/corti/KYKY_tMLElmbM71T/images/assistant-appstore-badge.svg?fit=max&auto=format&n=KYKY_tMLElmbM71T&q=85&s=64678a2176860cdb942fc300cec0c606" alt="Download on the App Store" style={{ height: "clamp(40px, 4vw, 56px)" }} width="120" height="40" data-path="images/assistant-appstore-badge.svg" />
  </a>

  <a href="https://play.google.com/store/apps/details?id=app.corti.assistant" style={{ textDecoration: "none", borderBottom: "none", lineHeight: 0 }}>
    <img src="https://mintcdn.com/corti/KYKY_tMLElmbM71T/images/assistant-playstore-badge.svg?fit=max&auto=format&n=KYKY_tMLElmbM71T&q=85&s=d5164f7be4c7cceee567b885a440b565" alt="Get it on Google Play" style={{ height: "clamp(40px, 4vw, 56px)" }} width="135" height="40" data-path="images/assistant-playstore-badge.svg" />
  </a>
</div>

## Related reference

* [API Reference Overview](/assistant/api-reference)
* [configureApp()](/assistant/api/configure-app)
* [Web Component API](/assistant/web-component-api)