PreviewThis page documents the release that launches on 01/01/2027. Packages, images and sign-up open then, and details may change before it.

Docs / Get started / Quickstart

Quickstart

Ready

TL;DR

In about five minutes, bring the whole system up on your laptop or a stock VM — PostgreSQL, the server, and a demo relying party with users — then drive a real signed ceremony end to end. One container stack on your own machine. Registering a licensing account and downloading the license are the only steps that contact Ydentifi; the running deployment never does.

Who this is for: anyone evaluating Ydentifi for the first time who wants to see it work before reading anything else. You will finish with a running deployment and one approved challenge. For the concepts behind what you just did, follow the links in What just happened.

Before you start

Docker running on your machine (Docker Desktop is fine).
The ydfi CLI — it ships as a container, so you pull and run it like the server. See CLI.
A free license: register with ydfi register (your email, legal name, licensee type and country), enter the code we email you, then download the license with ydfi pull. The same free license runs a real production deployment; see Get a license.

Grab the CLI once — pull the image and alias it so every ydfi command below runs inside the container:

# pull the ydfi CLI image  (published at launch)
$ docker pull ghcr.io/ydentifi/ydfi:latest
# alias it so every `ydfi …` below runs in the container. It mounts your
# working dir, the Docker socket the CLI drives, and ~/.config/ydentifi,
# where the API key from `ydfi register` is kept for the next `ydfi pull`
$ mkdir -p ~/.config/ydentifi && chmod 700 ~/.config/ydentifi
$ alias ydfi='docker run --rm -it -v "$PWD":/work \
      -v "$HOME/.config/ydentifi":/config/ydentifi -e XDG_CONFIG_HOME=/config \
      -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/ydentifi/ydfi'
$ ydfi --version

A free license authorizes the deployment before it will serve. Register once, then pull a license and apply it:

# register once: a code goes to your inbox, valid for 10 minutes and up to five
# attempts, and you enter it at the prompt
$ ydfi register --email you@acme.example --legal-name "Acme Ltd" \
      --licensee-type company --licensee-id-scheme vat \
      --licensee-id-value BG123456789 --country BG
# download the free license (50 users) and install it in the directory the local
# stack mounts. No image carries a license: the server reads the one you install.
# A server in a container needs the license's directory mounted, never the file alone
$ ydfi pull
$ ydfi license apply --license-file license.jwt --output-path docker/license/license.jwt

Registering and downloading are the only steps that contact Ydentifi, and they run from your terminal. Everything below runs against your local stack, and once running, the deployment never contacts Ydentifi: no renewal call, no heartbeat. When you need the next license, you download it the same way.

Five minutes#

Step 1 · Boot the stack

Bring it up locally

The first run mints your local PKI and per-install secrets (bootstrap); after that, up starts PostgreSQL, the composition-seeder, and the server on your machine over mutual TLS.

# first time only: mint local PKI + per-install secrets
$ ydfi deploy local bootstrap
# brings up postgres + composition-seeder + server, locally
$ ydfi deploy local up
✓ postgres   ready
✓ server     listening on localhost:50057 (mTLS)

Step 2 · Seed a demo

Create a relying party & users

This provisions a demo relying party, a handful of opaque users, and prints enrollment QR codes to the terminal.

# creates a demo relying party + users, prints enrollment QR codes
$ ydfi seed demo
✓ relying party  demo-rp
✓ users          5 created (opaque ids)
▒▒ scan a QR below to enroll a device ▒▒

Step 3 · Enroll

Link a device

Install the Ydentifi authenticator, then scan one of the printed QR codes. That runs the enrollment ceremony and binds the device to an opaque identity — no personal data is exchanged.

 App Store
iOS ▶ Google Play
Android

The app runs on a real phone, not the iOS Simulator, and the phone must reach your server with TLS end to end: a TCP pass-through works, a proxy that ends TLS does not. The local stack listens on this machine only, so for a phone, run the server where the phone can reach it: see Deploy and The phone cannot reach the deployment.

Step 4 · Drive a ceremony

Issue & approve a challenge

Issue a signed challenge to the enrolled user. Approve it on the device under your biometric; the server verifies the signature against the device’s attested key and prints APPROVED.

# issue a signed challenge to the seeded user; approve it on the device
$ ydfi seed challenge
→ challenge 01HZX5N6PK…  waiting for the device…
✓ APPROVED  signature verified against the enrolled key

Step 5 · Look around

Check the deployment

A one-line health snapshot confirms the database pool, certificate validity, and background reapers.

# deployment-wide health snapshot
$ ydfi admin health
db pool  ok   ·   certs  valid   ·   reapers  running

What just happened#

In five minutes you ran the full ceremony against a real, self-hosted deployment:

The server and database run entirely on your machine — there is no Ydentifi cloud in the path.
Your users are opaque identities; the deployment holds no personal data about them.
The device signed the exact challenge with a hardware-bound key, and the server verified it — the same mechanism you would use in production.

Tear it down#

When you are done, stop and remove the local stack:

$ ydfi deploy local down

Where to go next#

Your first ceremony — the same flow from your own code, step by step.
Integrate: step-up — drop one ceremony in front of your highest-stakes action.
API reference — every RPC, with runnable examples.

Relates to

← Previous

Security model

Your first ceremony

The ceremony CLI Deploy Integrate: step-up