The ceremony
ReadyEvery authentication and every action-approval in Ydentifi follows the same four-move shape: a device enrolls once by scanning a single-use code, then for each sensitive action the server issues a challenge, the device signs the exact details under a biometric, and your server verifies the signature. No personal data changes hands, and nothing leaves your infrastructure.
Who this is for: everyone integrating or evaluating Ydentifi — this is the core mental model the rest of the docs build on. Read it once and the API, the factors, and the guides all make sense. For the exact calls, jump to IssueAuthChallenge in the API reference.
The four moves#
One shape covers both “prove it’s really this user” and “prove they approved this exact action.” Enrollment happens once per device; the other three moves repeat for every challenge.
Bind the device
A single-use invite ties the user’s device to their opaque identity, and a hardware-bound key pair is generated inside the device’s secure element. The private key never leaves the hardware; only the public key is registered. No personal data is exchanged. See Enroll & link devices for the full flow.
Ask for proof
When your product reaches a sensitive action, your server calls Ydentifi for a challenge carrying the exact on-screen details of that action — e.g. “Approve €4,200 transfer to ···· 8842” — and the required identity proof tier. The challenge reaches the enrolled device by QR scan or pull-stream; no third-party push is involved.
Approve on device
The device shows those exact details and, once the user passes the tier’s biometric (and location, if required), signs a canonical payload with the hardware-bound key. The signature is meaningless unless it covers precisely what the user saw.
Check the signature
The deployment verifies the returned signature against the public key the device enrolled with and hands your application the verdict. If it is approved, the action proceeds — the decision, and the user’s identity behind the opaque token, stay entirely yours.
What gets signed#
The device does not sign “yes.” It signs a canonical payload — a deterministic serialization that binds the decision to the specific request. Conceptually:
challenge_id 01HZX5N6PKRHQGZ7T0F8YJM3WB
action_digest sha256("Approve €4,200 transfer to ···· 8842")
device_key <public key of the enrolled device>
verdict APPROVED
location bucket:allowed // a separate dimension, not a higher level
Because the action text is hashed into the signed bytes, a man-in-the-middle who relays your login but alters the amount or destination produces a signature that will not verify. There is nothing to replay and nothing to swap.
Why this is phishing-resistant#
Phishing resistance here is structural, not a heuristic:
- Per-action binding. The signature covers the exact details the user saw, so a relayed or altered request breaks it — unlike a one-time code or a bare tap-to-approve, which authenticate a session but not a specific action.
- Hardware-bound keys. The signing key lives in the secure element and is non-exportable, so there is nothing in a device backup for malware to lift.
- Enrollment binds to one deployment. The device-linking code carries your deployment’s address and a single-use token. The code also carries a pin over your deployment’s own root, and the app accepts a connection only from a certificate that chains to it, then talks to that address and no other for the life of the account. See Enroll & link devices.
The ceremony never carries a name, email, or number — only the opaque identity, the action text you chose to display, and cryptographic material. Ydentifi never receives these identifiers, so it is neither controller nor processor; you remain the controller. See Opaque identities in the glossary.
Terminal states#
A challenge starts PENDING and moves exactly once into a terminal state. Your server observes this over a server-stream (AwaitChallenge) — no polling, no webhooks.