Skip to content

1. Overview

What the Link Identity Platform is, what it does and does not do, and the capabilities every Link product builds on.

1.1 What It Is

Link Identity Platform is a general-purpose biometric identity service that provides a fully configurable identity stack to all tenants. Every tenant can enable the capabilities they need: user management, authentication, KYC verification, palm biometrics, sessions, and compliance.

1.2 Core Function

User Management: signup (OTP, email/password, Google, Apple) → user_id created
KYC [POST-MVP]: user_id + provider (Nafath, Onfido, etc.) → verified identity
Enrollment: user_id + palm_template → stored mapping
Verification: user_id + palm_scan → match result + metadata (1:1)
Identification: palm_scan → user_id (1:N search)

Diagram 1.1 — System Architecture Overview

flowchart TB
    subgraph Clients
        MA[Mobile App]
    end

    subgraph Identity-Managed Devices
        PS[Personal Scanner]
        POS[POS / Kiosk]
        AS[Access Gate]
    end

    subgraph Link Verticals
        ENV[Envoy Gateway]
        WB[Wallet Backend]
        AB[Access Backend]
    end

    subgraph Integrators
        IG[InvestGlass]
        PB[PartnerBank]
        HA[HealthApp]
    end

    subgraph Link Identity Platform
        WC[Web Console]
        API[Identity API<br/>FastAPI]
        DB[(PostgreSQL)]
        RD[(Redis)]
    end

    subgraph External Providers
        subgraph KYC Providers
            NAF[Nafath]
            ONF[Onfido]
        end
        subgraph Palm Vendors
            LN[X-Telcom BioWave Pass]
        end
        subgraph Social Auth
            GOO[Google]
            APL[Apple]
        end
        SMS[SMS Gateway]
        EMAIL[Email Service]
    end

    %% Device connections (all mTLS to Identity)
    MA -->|JWT via JWKS| ENV
    PS -->|mTLS| API
    POS -->|mTLS| API
    AS -->|mTLS| API

    %% Vertical connections
    ENV -->|X-User-ID| WB
    ENV -->|X-User-ID| AB
    WB -->|Client Credentials| API
    AB -->|Client Credentials| API
    API -->|authorize §10| WB
    API -->|authorize §10| AB

    %% Integrator connections
    IG -->|Client Credentials| API
    PB -->|Client Credentials| API
    HA -->|Client Credentials| API

    %% Identity Platform internal
    WC --> API
    API --> DB
    API --> RD

    %% External provider connections
    API -->|KYC Port| NAF
    API -->|KYC Port| ONF
    API -->|Palm Port| LN
    API --> GOO
    API --> APL
    API --> SMS
    API --> EMAIL

All capabilities available to all tenants (configurable per tenant): - User creation and management (platform-created or integrator-provided user_id) - Multiple auth methods (OTP, email/password, Google, Apple) - Session tokens with refresh (JWT) - KYC verification (pluggable providers: Nafath, Onfido, etc.) — [POST-MVP], §7 - Palm enrollment, verification (1:1), and identification (1:N) - Verification and identification metadata (confidence, timestamp) - Account linking (across auth methods) - Multi-tenant isolation - Consent management and compliance (DSR, enhanced audit) - Device fleet management — pairing, mTLS, revocation for pos/gate/kiosk/personal-scanner (§9) - Device-initiated palm transactions — synchronous broker to product backends (§10)

Each capability is configurable per tenant. Tenants enable only what they need.

Identity identifies and routes; it does not decide product business outcomes, and it is not a full OIDC provider.

Item Reason
Full OIDC provider (authorization endpoint) Post-MVP. May be added when third-party "Login with Link" is needed.
SSO / SAML Post-MVP. Not needed for the current B2B2C model.
Product business logic (charge wallet, grant access) The product's domain — Identity identifies the user and routes the decision via the broker (§10); it does not charge or grant access.

1.5 Core Capabilities

All capabilities are available to all tenants, configured individually per tenant (see §4.5 for the settings, §4.6 for examples).

Capability Default Configurable Via
User registration Available Per-request on POST /v1/users
Auth methods All enabled auth_methods
Session tokens Enabled with auth Enabled when auth is configured
Account linking Always enabled —
KYC verification Not required kyc_required (KYC integration is [POST-MVP] — §7)
Palm enrollment Available Always available
Verification (1:1) Available Always available
Identification (1:N) Available Always available