Launch on 01/01/2027Licenses available from 01/01/2027
Docs / Concepts / Architecture & topology

Architecture & topology

Ready
TL;DR

Ydentifi is a small set of parts you run: a server (one container + PostgreSQL), the apps and SDKs at the edges, and a CLI to operate it — with no Ydentifi cloud in the authentication path. One deployment can serve many relying parties, and because it holds only opaque tokens, you can host it anywhere while your personal data stays isolated wherever the law requires.

Who this is for: architects and decision-makers working out where Ydentifi runs, how tenants are separated, and where data lives. For the step-by-step of standing it up, see Deploy.

The shape#

Ydentifi is deliberately small: one engine you host, thin clients at the edges, and a hard line between the opaque tokens it holds and the personal data it never sees.

The whole systemEvery component that exists.YDENTIFI— the supplier. None of this is installed by a customer.Licensing serviceissues signed licensesLicense administrationruns the license businessBuild and testbuilds and proves the systemLoad testingcapacity evidencea signed license file, replaced each yearTHE DEPLOYMENT— two things to run, on the customer’s own infrastructureThe Ydentifi serverone program — licensed — three portsport 1the applicationport 2phonesport 3the operatorPostgreSQLthe only other thing requiredOpenTelemetry collectoroptional · the customer’s ownCertificates, keys and configuration — files the operator holdsydfithe operator’s command lineWHO CALLS ITThe relying party’s applicationtheir backend, their users, their dataopen-source client library · 8 languagesThe end user’s phonekeys inside the security chipfree app + open-source libraryOne licensed program. The tools and the applications are free; the libraries are open source.Nothing above the dashed line is in the path of a login or an approval.
Every component, in three zones: what Ydentifi supplies, what you run, and what calls it. Nothing above the dashed line sits in the path of a login or an approval.
Your Ydentifi deploymentone server + PostgreSQL · host anywhere
↓   gRPC over mutual TLS   ↓
RP 1EU subsidiary
opaque users
RP 2US subsidiary
opaque users
RP 3Middle East subsidiary
opaque users
Isolated · never touches Ydentifi
Your personal-data store · e.g. EUReal names, emails, and records live here. Ydentifi holds only opaque tokens; you keep the opaque_id → person mapping.

One deployment serves many relying parties — here, three regional subsidiaries. Each RP’s users are faceless opaque tokens to Ydentifi; the real personal data sits isolated in whatever jurisdiction the law requires, in systems Ydentifi never touches.

One deployment, many relying parties#

A single deployment can serve many relying parties at once — separate apps, business units, or, as above, regional subsidiaries. Each RP authenticates with its own mutual-TLS client certificate, and every call is implicitly scoped to that certificate. One RP can never see another’s users or challenges; a cross-tenant read returns NotFound, so existence never leaks across the boundary.

This is why the request bodies are so lean: the certificate already says who is calling, so most RPCs carry no tenant identity at all.

Where your data lives#

Ydentifi stores no personal data — only opaque identities and cryptographic material. The mapping from an opaque token back to a real person lives entirely on your side, in systems Ydentifi never touches.

Two consequences fall straight out of that:

  • Host it anywhere. Because the deployment holds no regulated personal data, it is not bound to the jurisdiction where that data must legally reside. Run the authentication layer wherever it is cheapest, fastest, or most convenient — even fully air-gapped. The deployment never phones home to Ydentifi on any tier: it runs on a license file until that file expires, then you install the next one (see Get a license).
  • Data residency stays yours. Your personal data sits exactly where the law requires (an EU store, in the diagram), isolated from the auth layer. You remain the data controller. Ydentifi is neither controller nor processor: your users’ data never reaches it.
ⓘ A hard line

Nothing in the authentication path carries a name, email, or number. That single pillar is what lets one deployment safely serve subsidiaries across different regions while each keeps its own personal data where it belongs. See Security model for who secures what.

The moving parts#

Three ports, four servicesEach port trusts one set of certificates. A credential issued for one is worthless at the others.PORT 1The applicationTRUSTS CERTIFICATES FROMRelying-party CA onlyHANDSHAKERequireAndVerifyClientCertSERVICES ON ITIdentityServiceevery call the customer’s backend makesPORT 2PhonesTRUSTS CERTIFICATES FROMDevice CA onlyHANDSHAKEVerifyClientCertIfGivenSERVICES ON ITDeviceOnboardServiceno certificate yet — a single-use invite insteadDeviceGatewayServicecertificate required, checked per callPORT 3The operatorTRUSTS CERTIFICATES FROMOperator CA onlyHANDSHAKERequireAndVerifyClientCertSERVICES ON ITAdminServiceinspection and operator actionA certificate is refused unless it wassigned by the relying-party CA and itsfingerprint matches the one on record.One port, two services. The handshakeallows a phone with no certificate; theper-call check decides which RPCs thatphone may reach.Optional. A deployment that neverenables it simply has no operator portopen.A fourth port carries metrics, reachable only with an operator certificate and off unless the deployment turns it on.
Each port, the certificate authority it trusts, its handshake mode, and who is allowed to call it.
  • The server — the engine you self-host: enrollment, challenges, policy, licensing. One container plus a PostgreSQL database. It makes no outbound calls on the auth path.
  • The authenticator app — native iOS and Android apps at launch, holding enrollments and signing challenges. Or embed the ceremony in your own app with the Swift device SDK — Kotlin for Android, both at launch.
  • The backend SDKs — eight languages that wrap the gRPC API, or call it directly. This is how your product talks to the server.
  • The CLI — one tool to provision, deploy, operate, and simulate the whole system. The CLI is the product surface; there is no GUI-only operation.
  • The trust chain — your own certificate authority, and the RP certificates it issues. You hold these keys; Ydentifi never does.

No cloud in the path#

Every RP-facing call is gRPC over mutual TLS — there is no HTTP gateway and no Ydentifi-hosted service in the authentication path. Challenges reach devices by QR or a pull-stream, so there is no Apple or Google push for a platform vendor to throttle or observe. A deployment that has been licensed can run entirely offline. See Why gRPC-only for the reasoning.

What a call passes throughSix checks before a handler runs. Each one can end the call on its own.1TLS handshake  transportA client certificate is required. It must chain to the relying-party authorityconnection refused2Wire-format checkThe message must be exactly the declared shape — unknown fields are not toleratedInvalidArgument3LicenseIs this deployment licensed to serve this call at all?FailedPrecondition4License capacityIs it inside its seat limit?ResourceExhausted5Caller identityWhich relying party is this? The certificate fingerprint is compared with the one on recordUnauthenticated6Call policyIs this caller’s role allowed to make this call on this listener?PermissionDenied7Error sanitising  return pathOn the way back only: internal detail is replaced with a typed reasonThe handlerIt runs with an authenticated caller already in hand, and never touches a certificateLayers 2–6 are the same program on every port. On the phone port, layer 5 identifies a device; layer 6 reads each port’s own table.
The seven layers a call passes through before it reaches any business logic.
Relates to
← Previous
Glossary
Next →
The ceremony
Security modelDeployOpaque identitiesWhy gRPC-only
Opens on 01/01/2027

Available at launch

Until then, you can try the whole ceremony on your own phone.

Try the live demo