Security Best Practices

Overview

Nafsi is a SaaS identity verification (IDV) platform optimized for speed, configurability, and strong support for African identity documents.

The platform is built around:

• Dynamic, customer-configured verification workflows
• SDK-based (Web, Android, iOS, React Native) and direct API ingress
• Message-driven backend orchestration
• Fast, stateless verification services executed by internal and external providers
• A defense-in-depth security model (OAuth 2.0 client credentials, refresh tokens, and mTLS-protected webhooks)

The central component is the Nafsi IDV Gateway (also referred to as the Windmill API Gateway in some integration contexts). It is responsible for:

• Authentication and request validation
• Workflow resolution
• Step orchestration
• Result aggregation
• Persistence coordination
• Notification triggering

The architecture intentionally avoids a traditional monolithic REST processing core. Instead, internal processing is predominantly asynchronous and message-driven to maximize scalability and resilience.

Core Architectural Principles

• Workflow-driven execution (data-defined, not hard-coded)
• Message-oriented internal orchestration
• Stateless verification services
• Runtime configurability (no redeploy required for new workflows or checks)
• Strong authentication and explicit trust boundaries
• Deterministic, traceable outcomes per verification
• Transparent billing via per-check unit consumption

High-Level Components & Data Flow

flowchart TD

    A[Client App / SDK / API Call] -->|HTTPS + OAuth2 Bearer / refresh token| B[Windmill API Gateway(idv-gateway-v2 queue)]
    B --> C[Authentication & Request Validation]
    C --> D[Dynamic Workflow Resolution<br>(from DB)]
    D --> E[Sequential Execution of Checks]
    
    E --> F[OCR Extraction <i>(mandatory)</i>]
    E --> G[MRZ Parsing]
    E --> H[Face Matching]
    E --> I[Liveness Detection]
    E --> J[Document Authenticity]
    E --> K[Age / Address Verification]
    E --> L[Custom Verification Check<br>(via webhook)]
    
    E --> M[Result Aggregation & Enrichment]
    M --> N[Persistence<br>(results, audit trail)]
    N --> O[Response to Client<br>(callback / polling / webhook)]
    N --> P[Notifications<br>(webhook, email, SMS)]

Main Building Blocks

Component	Responsibility	Communication Style
Client Apps / SDKs	Initiate verifications, send images, receive results	HTTPS + OAuth2
Windmill API Gateway	Auth, workflow resolution, orchestration, aggregation, notifications	AMQP RPC (idv-gateway-v2)
Workflow Store	Holds customer-defined workflows (steps, order, thresholds, manual review rules)	Database
Verification Services	Execute individual checks (OCR, MRZ, face match, liveness, etc.)	Internal RPC / HTTP
Custom Check Webhooks	Customer-defined business logic mid-flow (e.g. duplicate check, scoring)	HTTPS + mTLS
Event Notification Webhooks	Real-time delivery of verification events (completed, failed, manual review)	HTTPS + mTLS
Persistence Layer	Stores verification results, audit logs, activity history	Database
Redis (control plane)	Runtime config, integration credentials, feature flags	In-memory key-value

Key Flows

1. Typical Verification Request Flow

1. Client (SDK or direct API) authenticates and obtains access and refresh tokens
2. Client sends POST request with images (base64 JPEG), workflow_id, and optional config
3. Gateway validates token and resolves workflow definition
4. Verification steps execute sequentially (OCR first, then dependent checks)
5. Results are aggregated and evaluated against thresholds and manual review rules
6. Outcome and audit trail are persisted
7. Gateway returns immediate HTTP response (sync mode) or publishes async result
8. Optional notification webhooks are triggered

2. Webhook Flows

Two webhook patterns are supported:

1. Event Notifications

   • Asynchronous push of lifecycle events --> Examples include: verification.completed, verification.failed, verification.review_required

2. Verification Check Webhooks

   • Synchronous mid-flow customer decision point
   • Customer returns pass / fail / review

Both webhook types enforce:

• Mandatory mTLS
• Signed requests (optional HMAC)

Security Model

• Ingress: OAuth 2.0 Client Credentials (client_id + client_secret → tokens)
• SDKs: Use refresh tokens; client secrets are never exposed in client environments
• Webhooks: Mandatory mTLS with optional HMAC signing
• Internal services: Service-to-service authentication (API keys and/or mTLS)
• Images & payloads: Encrypted in transit, processed transiently, and deleted after processing

Why This Architecture?

• Speed — message-driven pipeline with local-first processing minimizes latency
• Flexibility — customer-defined workflows eliminate redeploy cycles
• Scalability — competing consumers enable horizontal scale
• Observability — every step emits traceable events
• Security — explicit trust boundaries and cryptographic enforcement

This architecture enables Nafsi to remain fast, configurable, and secure while supporting diverse identity verification use cases across African markets.**