> ## 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.

# Smart TV and keyboard-free surfaces

> Signing in and confirming where there is nothing to type on: how this differs from device flow and what Veriqa already has for it.

A television, a kiosk, a three-button device: start the sign-in where typing is awkward and confirm
it in a messenger on the phone. Why this matters and for whom is covered on the
[Smart TV and keyboard-free surfaces](https://veriqa.app/whats-next/smart-tv?lang=en) page. Here is what
the product has for it today.

## Relationship to OAuth 2.0 Device Flow

The first question people ask is whether this restates RFC 8628. It does not — the standard and
Veriqa answer different questions and live on different layers.

| | RFC 8628 | Veriqa |
| - | - | - |
| The question it answers | how a device without a browser obtains a token | **how** the user proves they are who they claim |
| What it defines | `device_code`, `user_code`, `verification_uri`, token-endpoint polling | the confirmation method — possession of a trusted channel |
| On the authentication method | says nothing: the `verification_uri` may hold anything, a password included | that is its entire subject |

The overlap is only in the shape of the interaction — "start where typing is awkward, confirm on the
phone". There is no protocol duplication: a browser sign-in through Veriqa lives entirely inside
`authorization_code`, and the server-to-server entry point ends in an exchange of its own on the token
endpoint.

## What it adds compared with device flow

* **It collapses the verification step.** In device flow the second device goes through another
  full sign-in: open the address, type the code, authenticate. Here it is one tap in a messenger
  where the session already exists. Strictly speaking this is not an improvement on the standard
  but a method dropped into the hole the standard deliberately left empty.
* **It targets code phishing.** A known weakness of device flow: the attacker starts the flow on their
  side and talks the victim into entering their code — the standard does nothing to bind the initiator
  to the confirming party. On a browser sign-in Veriqa shows the initiator's context at
  the moment of confirmation, and that addresses precisely this vector.
* **It links a channel in the same step.** Outside device flow's scope entirely: the standard
  ends at issuing a token.

<Warning>
  Showing the initiator's context is **not protection against relay or MITM**. The measure is
  probabilistic and works through the user's attention. The reinforcement is narrow; plain device
  flow does not have even that.
</Warning>

## What exists today

**A browser or a webview on the device.** If the platform offers a webview, the ordinary sign-in
through `/connect/authorize` works: a page with a QR code, confirmation in a messenger, and the
application receives OIDC tokens.

**The server-to-server confirmation entry point — no browser needed.** The application calls
`POST /api/transaction/confirmation`, authenticating with client credentials and naming a declared
action type (`action_type`), and receives a `channel_entry` in the response: the address for the
user (`url`) — the channel's deep link or the channel-selection page — and the same address as a
ready-made QR image (`qr`, a PNG data URI) with the moment it stops being valid (`valid_until`). An
application on any TV SDK can show that image; the device needs no browser for it. The user scans
the QR code with their phone and confirms in the messenger. Send `include_channel_entries: true` and
the response also carries `channel_entries` — a deep link with its QR code for every available
channel — so the screen can offer a choice of messengers.

The QR image carries the product attribution: a "Powered by Veriqa" strip under the code, below its
quiet zone, so the picture is taller than it is wide — leave room for the strip rather than fitting
the image into a square frame. The strip is part of what the software renders under its license:
cropping it off is technically possible, and whether you may do so is a licensing matter, not a
setting.

The application reads the outcome with `GET /api/transaction/{id}/result`: `confirmed`, `declined`,
`expired` or `failed`, and `pending` while there is no answer yet. If expected identities
(`expected_identities`) were passed at creation, the result also tells whether the confirming
person matched the expected one (`matched_type`).

**Signing in without a browser, when the application has a backend.** Once the outcome is
`confirmed`, the application's server exchanges the transaction for the `id_token` of the person who
confirmed: `POST /connect/token` with `grant_type=urn:veriqa:params:oauth:grant-type:confirmation`,
the `transaction_id` and a `scope` that contains `openid`. The server keeps the `sub` from the token
next to its own account and opens its own session on the TV. The client needs
`AllowClientCredentials`, `AllowConfirmationTokenGrant` and `openid` in `AllowedScopes`; the exchange
and its rules are described in
[Linking from your server](/docs/scenarios/channel-linking#linking-from-your-server-without-a-sign-in).

How this differs from a browser sign-in:

* **No `refresh_token`.** A transaction is redeemed once; the long-lived session on the TV is the
  application's own.
* **It is a confirmation, not a sign-in.** It needs a declared `action_type` with its text, and with
  the grant enabled the application learns the confirming person's channel identity in **every**
  confirmation of that client. A separate client for the TV scenario is worth considering.
* **The initiator's context is what your backend writes.** The request comes from your server, not
  from the TV, and the QR is a bearer entry: whoever opens it first confirms, and the `sub` is
  theirs. Put the device and the place into the action type's text through slots your backend
  fills.

<Note>
  Client credentials are the application's secret. Call the server-to-server entry point from your own
  server, not from code on the device: a secret shipped inside a TV application can be extracted.
</Note>

## What does not exist today

* **A path for a device with no backend of its own.** The client secret cannot live on the device,
  so a TV application without a server has no way to obtain tokens yet. A full implementation of Device
  Authorization Grant (RFC 8628) is in progress.
* **There are no native SDKs for TV platforms**: the server-to-server entry point and the exchange are
  plain HTTP requests.


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