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

# Hop mode

> A short one-time link in the QR code instead of the channel link: a light QR code, a scan signal on the computer, a launch page on the phone and the context of the scanning device. Why it is better and how to turn it on.

In hop mode the QR code on the sign-in page carries a **short one-time link to your Veriqa server**
instead of the messenger link. The phone opens it, the server records the scan and sends the user
on to the messenger or to email. That one extra hop gives the best user experience Veriqa offers.

<Tip>
  **We recommend turning hop mode on.** It is off by default only because it needs an issuer set as
  an absolute `https` address that the phone can reach. See [how to turn it on](#how-to-turn-it-on)
  below.
</Tip>

## Key differences

| | Without hop mode | With hop mode |
| - | - | - |
| **What the QR code carries** | The channel link — a messenger deep link or an email. It is long, so the QR code is dense | A short link to your server. The QR code is light, any phone camera reads it at once, and its density does not depend on the channel |
| **What the computer shows after the scan** | Nothing until the channel answers the start or the confirmation arrives | Right away: "QR code scanned. Continue in Telegram." The channel choice gives way to the instruction "Continue on your phone…" with a "Choose another way" button |
| **One QR code for every channel** | No — each channel has its own QR code | Yes: `QrMode: Unified`, and the user picks the channel on the phone |
| **If the messenger app does not open** | Nothing to fall back on: the hop to the app is entirely up to the messenger | A launch page on the phone opens the app by itself and keeps a button to try again |
| **What is known about the scanning phone** | Nothing | Time, IP, browser, OS and device type — risk signals next to the [initiator context](/docs/concepts/initiator-context) |
| **The link reopened from another browser** | Not visible | Flagged — `WarnOnRepeatScan`, on by default |
| **What the deployment needs** | Nothing extra | An issuer that is an absolute `https` address the phone can reach |

## What the user sees

1. On a computer, a TV or a kiosk, the user scans the QR code with their phone camera.
2. The phone opens the short link. The sign-in page on the computer immediately says "QR code
   scanned" and shows what to do next.
3. The phone moves on to the messenger — directly or through a launch page, depending on the
   [redirect style](#redirect-style).
4. The user confirms with a single tap, and the sign-in completes on the computer.

If they scanned with the wrong device or changed their mind, the "Choose another way" button brings
the channel choice back on the same page, for the same sign-in. Once the channel has answered the
start, the button goes away: the sign-in is now bound to that channel.

## Redirect style

| `RedirectStyle` | What the phone gets |
| - | - |
| `Interstitial` (default) | A launch page: it opens the messenger app by itself and keeps a button in case the app did not open |
| `Direct` | A redirect straight to the messenger, with no page in between |

`Interstitial` is more reliable where a direct jump into the messenger app does not always work. The
Email channel has rules of its own — see [Email under hop mode](/docs/guides/channels#email-under-hop-mode).

## How to turn it on

```json appsettings.json theme={null}
{
  "Veriqa": {
    "OpenIddict": {
      "Server": { "Issuer": "https://auth.example.com" }
    },
    "HopMode": { "Enabled": true }
  }
}
```

Turn it on for the whole server, for a single channel (`Veriqa:Channels:{Channel}:HopEnabled`) or for
one application, in its OIDC client record. All the keys, and the order in which they override
each other, are in the [Veriqa:HopMode](/docs/reference/configuration#veriqahopmode) reference.

Every hop link is built on `Veriqa:OpenIddict:Server:Issuer`, so with hop mode on, the issuer must be
an absolute `https` address — otherwise the server does not start. To try hop mode on your own
machine, expose Veriqa through an HTTPS tunnel — see
[Testing the integration locally](/docs/integrations/local-testing#hop-mode-on-a-local-setup).

## Security

* **It is not a link shortener.** The server always derives where to send the user from the
  transaction, never from the link, so a hop link cannot be turned into an open redirect.
* **The context of the scanning phone is a risk signal, not an authentication factor.** It helps
  spot a request that is not the user's own, but the sign-in is still confirmed by the user in their
  own messenger. The `HopMode.Collect*` keys decide what is collected: IP, browser and device type
  are on by default; the browser fingerprint and geolocation only if you turn them on.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.