Nodela Verify

Introduction

What is Nodela Verify?

Nodela Verify is a hosted identity verification and trust orchestration platform that enables developers to integrate biometric verification, document verification, wallet ownership validation, OTP confirmation, and verifiable credential issuance into their applications through a unified API-driven workflow.

The platform is designed around a session-first verification architecture, where developers create verification sessions from their backend systems and redirect users into a hosted verification experience managed entirely by Nodela Verify.

Instead of manually orchestrating biometric uploads, challenge progression, or document capture flows, developers interact with a single verification session lifecycle while the platform coordinates the underlying verification pipeline automatically.

Platform Goals

Nodela Verify is designed to solve several common integration problems:

• fragmented verification workflows
• inconsistent capture experiences
• insecure client-side media uploads
• difficult biometric orchestration
• unreliable verification state management
• poor webhook synchronization
• high implementation complexity

The platform provides a consistent hosted verification layer that abstracts the complexity of multi-step identity verification while preserving flexibility for advanced integrations.

Core Integration Philosophy

The platform follows four primary architectural principles:

1. Session-First Architecture

Every verification process begins with the creation of a verification session.

A session acts as the orchestration container for:

• verification checks
• challenge progression
• verification state
• trust scoring
• result aggregation
• credential issuance

This allows all verification evidence and outcomes to remain correlated under a single lifecycle object.

2. Hosted Verification Challenges

Interactive verification tasks are hosted and managed by Nodela Verify.

Examples include:

• selfie liveness capture
• government ID capture
• NFC document verification flows
• challenge-based biometric interactions

Developers do not need to:

• build custom biometric UIs
• manage media uploads
• coordinate challenge transitions
• handle challenge expiration logic

The hosted verification flow automatically advances users through required verification stages.

3. Backend-Controlled Security

Sensitive operations are expected to originate from trusted backend infrastructure.

This includes:

• session creation
• credential issuance
• webhook processing
• wallet verification
• OTP orchestration

API keys must never be exposed in frontend or mobile applications.

4. Unified Verification Outcomes

All verification methods contribute to a single verification outcome model.

This includes:

• per-check statuses
• aggregate session status
• trust scoring
• verification metadata
• credential generation eligibility

The result is a consolidated verification profile that can be consumed consistently across applications and services.

High-Level Verification Flow

The standard verification lifecycle follows a predictable pattern:

1. Your backend creates a verification session.
2. The platform returns a start_url.
3. Your frontend redirects the user to the hosted verification flow.
4. Nodela Verify automatically orchestrates interactive verification challenges.
5. Verification results become available through webhooks, polling APIs, and session profile endpoints.
6. Your backend consumes the final verification outcome.
7. Optional verifiable credentials can be issued for completed sessions.

Hosted Flow Model

Nodela Verify uses a hosted challenge progression system.

Developers only launch a single browser entry point:

start_url

The platform internally handles:

• challenge ordering
• dependency management
• verification progression
• prerequisite enforcement
• redirect transitions
• verification completion

Supported Verification Methods

Verification methods can be combined into a single session depending on assurance requirements.

Verification Session Model

A verification session contains:

• session metadata
• requested verification checks
• per-check status information
• trust scoring data
• timestamps
• verification results
• challenge references
• credential issuance state

Sessions progress through well-defined lifecycle states such as:

Each verification check inside the session maintains its own independent state machine.

Interactive vs Non-Interactive Checks

Interactive checks

Interactive checks require direct user participation through the hosted challenge UI.

Examples:

• liveness detection
• document capture
• NFC document scanning

These checks are automatically orchestrated through the hosted browser flow.

Non-interactive checks

Non-interactive checks execute programmatically after required prerequisites are satisfied.

Examples:

• face matching
• trust scoring
• credential generation

These checks may execute automatically without additional browser interaction.

Trust Scoring

Completed sessions can produce an aggregate trust score.

The trust score represents the weighted confidence derived from completed verification checks and associated verification evidence.

Trust scores can be used for:

• onboarding decisions
• fraud prevention
• account recovery policies
• risk-based authentication
• compliance workflows

Verifiable Credentials

Nodela Verify supports issuance of W3C-compatible Verifiable Credentials (VCs) for completed verification sessions.

Credentials can contain:

• session identifiers
• verification outcomes
• trust scores
• completed checks
• cryptographic proofs

Issued credentials can later be independently verified through public verification endpoints.

Security Model

The platform is designed around a backend-mediated trust architecture.

Key security principles include:

• API keys remain server-side only
• hosted flows isolate biometric collection
• signed webhooks protect event authenticity
• temporary signed URLs protect media access
• verification sessions are project-scoped
• challenge expiration limits replay windows

Developers are expected to validate webhook signatures and securely persist verification state internally.

Recommended Integration Pattern

1. Backend creates verification session
2. Frontend opens start_url
3. Backend receives webhook events
4. Backend optionally polls session status for reconciliation
5. Backend stores verification outcome
6. Backend optionally issues credentials

This pattern minimizes implementation complexity while preserving strong operational reliability.

Intended Use Cases

Nodela Verify can be integrated into systems requiring identity assurance or ownership verification, including:

• fintech onboarding
• KYC/AML compliance
• digital banking
• marketplace trust systems
• account recovery workflows
• workforce identity verification
• crypto onboarding
• DAO participation systems
• high-risk authentication flows
• credential issuance systems

Quick Start Guide

This guide walks through the fastest path to integrating Nodela Verify into your application.

By the end of this section, you will be able to:

• create a verification session
• launch the hosted verification flow
• receive verification outcomes
• validate webhook events
• retrieve verification results

This is the recommended implementation path for all new integrations.

Overview

A complete Nodela Verify integration consists of four core steps:

1. Your backend creates a verification session.
2. Your frontend opens the returned start_url.
3. The user completes the hosted verification flow.
4. Your backend receives final verification results via webhook or polling.

The hosted verification system automatically orchestrates challenge progression internally. Developers do not manually manage biometric uploads or challenge transitions.

Prerequisites

Required infrastructure

• a backend server capable of making HTTPS requests
• a frontend application capable of opening external URLs
• a public HTTPS endpoint for webhook delivery
• secure server-side secret storage

Required knowledge

• REST APIs
• JSON request/response handling
• webhook processing
• server-side authentication
• HTTP status codes

Recommended stack

Environment Setup

Base API URL:

https://identity.nodela.co

Nodela Verify uses a single environment endpoint. There is no separate sandbox or production API base URL.

All requests must use Content-Type: application/json.

Obtaining API Keys

All API keys must be created from the Nodela Verify dashboard at verify.nodela.co.

Authentication can be performed using either:

X-Nodela-Key: <API_KEY>

API keys must:

• only be stored server-side
• never be exposed in browser code
• never be embedded in mobile applications
• never be committed to source control

Required Scopes

For a minimal session-based integration:

First Webhook Setup

Register your webhook endpoint before creating sessions, then include it in session creation.

{
  "webhook_url": "https://example.com/webhooks/nodela"
}

Webhook events are sent when sessions reach terminal states such as completed, failed, or expired.

Always verify the HMAC signature and reject mismatches.

Your First Verification Session

Endpoint: POST /sessions

Required scope: session:write

curl -X POST "https://identity.nodela.co/sessions" \
  -H "X-Nodela-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "checks_requested": [
      "liveness_detection",
      "document_capture",
      "face_match"
    ],
    "success_redirect_url": "https://example.com/verify/success",
    "error_redirect_url": "https://example.com/verify/error",
    "webhook_url": "https://example.com/webhooks/nodela"
  }'

Dependency rule: face_match requires liveness_detection and document_capture.

If dependencies are missing, session creation fails with 400 Bad Request.

Opening start_url

After session creation, redirect the user to start_url. This is the only required browser entry point.

window.location.href = session.start_url;

You should open start_url once and allow hosted progression automatically.

Do not manually orchestrate challenge URLs or direct biometric uploads.

Receiving Verification Results

Consume outcomes using webhooks, polling APIs, or profile endpoints.

Recommended approach: webhooks as primary source of truth, polling as reconciliation fallback.

Polling Session Status

Endpoint: GET /sessions/{id}/status

Required scope: session:read

curl -X GET "https://identity.nodela.co/sessions/<SESSION_ID>/status" \
  -H "Authorization: Bearer <API_KEY>"

Minimal Working Example

Backend:

• Create session
• Store session_id
• Return start_url to frontend
• Receive webhook and persist verification outcome

Frontend:

• Request verification session from backend
• Redirect user to start_url
• Handle success/error redirect

const response = await fetch("https://identity.nodela.co/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Nodela-Key": process.env.NODELA_API_KEY
  },
  body: JSON.stringify({
    checks_requested: ["liveness_detection", "document_capture", "face_match"],
    webhook_url: "https://example.com/webhooks/nodela",
    success_redirect_url: "https://example.com/success",
    error_redirect_url: "https://example.com/error"
  })
});

const session = await response.json();

return {
  session_id: session.id,
  start_url: session.start_url
};

Core Concepts

This section defines the foundational concepts, terminology, lifecycle semantics, and architectural behaviors used throughout the Nodela Verify platform.

Understanding these concepts is critical before implementing advanced integrations, operational workflows, or production-grade verification systems.

Platform Architecture Overview

Nodela Verify is built around a session-based verification orchestration model.

Developers interact with a higher-level lifecycle managed through:

• verification sessions
• verification checks
• hosted challenge flows
• webhooks
• polling APIs
• trust scoring systems
• verifiable credentials

The Session Model

A session is the primary orchestration object within Nodela Verify.

Sessions are created using POST /sessions and act as the container for requirements, progression, scoring, and outcomes.

Session Lifecycle

{
  "id": "session_uuid",
  "overall_status": "in_progress",
  "checks": [],
  "start_url": "https://...",
  "expires_at": "2026-04-14T17:30:00.000Z",
  "created_at": "2026-04-14T16:30:00.000Z"
}

Verification Checks

A check is an individual verification operation executed within a session.

Each check has its own state machine:

Hosted Challenge Flow

Interactive verification is driven from one browser entry point: start_url.

Hosted challenges provide consistent UX, stronger security, and simpler integrations.

Open this URL once and rely on hosted progression and webhooks for completion handling.

Automatic Check Progression

The platform determines sequence, prerequisites, and when non-interactive checks should run.

Example flow: liveness_detection → document_capture → face_match.

Verification Dependencies

face_match requires liveness_detection and document_capture.

Dependency violations return validation errors during session creation.

Verification Evidence

Trust Score

Completed sessions may produce trust_score in the range 0.0 → 1.0.

It reflects aggregate confidence from check outcomes and evidence quality.

Session Profiles

Detailed outcomes are available from GET /sessions/{id}/profile, including metadata, checks, trust score, and result payloads.

Redirect URLs

Webhooks

Webhooks are configured during session creation and are the recommended primary source of truth for production integrations.

Polling APIs

Credentials

Completed sessions can optionally generate verifiable credentials using POST /sessions/{id}/credential.

Credentials can include outcomes, trust scores, proofs, and verification metadata.

Verification Outcome Model

Per-check outcomes include status, score, metadata, and timestamps.

Aggregate session outcome includes overall status, trust score, credential eligibility, and a unified profile.

Session Expiration

Default session expiration is 60 minutes, configurable from 5 to 1440 minutes.

Expired sessions transition to expired and cannot continue processing.

Media Upload Policy

Modern integrations should not directly upload selfie frames, biometric streams, or document images.

Instead:

1. Create sessions
2. Open start_url
3. Consume verification outcomes

Authentication & Authorization

This section explains how authentication, authorization, API scopes, and access control work within Nodela Verify.

These mechanisms are critical for secure production integrations and proper access boundaries.

Security Architecture Overview

• API key authentication
• scope-based authorization
• project isolation
• backend-only privileged operations
• HTTPS-only communication

Authentication Model

Nodela Verify authenticates requests with project-scoped API keys.

Base API URL:

https://identity.nodela.co

All traffic must use HTTPS.

Authentication Methods

curl -X GET "https://identity.nodela.co/sessions/<SESSION_ID>/status" \
  -H "X-Nodela-Key: <API_KEY>"

Recommended for backend and middleware integrations: Authorization: Bearer.

API Key Scope System

Principle of Least Privilege

Use the smallest scope set required by each integration.

Authorization Failures

Project Isolation

API keys can only access resources that belong to the same project. Cross-project access is rejected.

Backend-Only Operations

• session creation
• credential issuance
• webhook validation
• polling APIs
• wallet verification
• document retrieval

API Key Rotation

Use regular rotation policies and a safe rotation flow:

1. Create new key
2. Deploy updated credentials
3. Verify successful traffic
4. Revoke old key

All keys are created from verify.nodela.co.

Webhook Authentication

Webhook requests include:

X-Nodela-Signature: sha256=<hex_hmac>

Treat signature verification as mandatory in production.

Security Best Practices Checklist

Recommended

• store API keys server-side only
• validate webhook signatures
• rotate credentials regularly
• use least-privilege scopes
• log verification events and persist session IDs
• use HTTPS everywhere

Avoid

• embedding keys in frontend code
• exposing privileged endpoints publicly
• skipping webhook validation
• storing secrets in source control
• over-scoping production keys
• trusting frontend verification state for decisions

Verification Flow Architecture

Nodela Verify uses a hosted orchestration engine built around sessions, ordered checks, and a single browser entry point.

Core flow behavior:

1. Your backend creates a session with ordered checks_requested.
2. The API returns a single start_url.
3. The hosted UI handles challenge ordering, dependencies, and redirects automatically.
4. Non-interactive checks execute after prerequisites are satisfied.
5. Results are delivered through webhooks and polling endpoints.

The platform internally handles:

• challenge sequencing
• dependency enforcement
• redirect completion behavior
• session expiration and terminal states
• automatic progression between interactive steps

Verification Types

The session-first model supports multiple verification methods that can be combined into one orchestration flow depending on your assurance policy.

Liveness Detection

Confirms that a real live person is present during capture.

Use it by adding liveness_detection to checks_requested, then read results from session status, profile, or webhooks.

Typical use case: selfie-based onboarding flows that require spoof resistance.

Document Capture

Captures a government ID in the hosted flow and performs document analysis for downstream use cases like face matching.

If needed, temporary viewing links can be requested through GET /document/:sessionId/view-link.

Document NFC

Validates NFC chip data from supported identity documents.

Use it for higher-assurance document-backed identity confirmation with chip-derived signals.

Face Match

Compares face evidence sources and returns whether they match within threshold.

Prerequisites:

• liveness_detection
• document_capture

OTP Verification

Validates one-time passcode ownership proof, typically email-based in the public API.

Use direct OTP endpoints for explicit flows, or consume results as a session check outcome when included in policy.

Wallet Signature Verification

Proves control of a blockchain wallet through signature validation.

Typical use case: Web3 account ownership verification with optional trust enrichment from wallet reputation.

Sessions API

Sessions are the main orchestration layer for hosted verification journeys. In most integrations, this is the primary API surface you will use.

Create Session

{
  "checks_requested": ["liveness_detection", "document_capture", "face_match"],
  "webhook_url": "https://example.com/webhooks/nodela",
  "success_redirect_url": "https://example.com/verify/success",
  "error_redirect_url": "https://example.com/verify/error",
  "expires_in_minutes": 60,
  "metadata": { "customer_id": "cus_123" }
}

Session Status

{
  "id": "e4582d65-1bf7-4a70-b71f-cb8e14a15ef9",
  "overall_status": "in_progress",
  "checks": [
    {
      "id": "7a5d8f85-5928-4d34-b1db-64fd18f7e766",
      "check_type": "liveness_detection",
      "status": "passed",
      "score": 0.93,
      "completed_at": "2026-04-14T16:32:02.000Z"
    }
  ],
  "expires_at": "2026-04-14T17:30:00.000Z",
  "created_at": "2026-04-14T16:30:00.000Z"
}

Session Profile

{
  "session_id": "e4582d65-1bf7-4a70-b71f-cb8e14a15ef9",
  "project_id": 12,
  "overall_status": "completed",
  "trust_score": 0.85,
  "checks": [
    {
      "check_type": "liveness_detection",
      "status": "passed",
      "score": 0.93,
      "result": {},
      "weight": 20
    }
  ]
}

Document APIs

Document Session

{
  "checks_requested": ["document_capture"],
  "webhook_url": "https://example.com/webhooks/nodela",
  "expires_in_minutes": 60,
  "metadata": { "ref": "doc_flow_001" }
}

View Link

NFC Verification

Biometric API

For modern integrations, use POST /sessions plus start_url for interactive capture. Use biometric endpoints mainly for readback, recovery, or advanced orchestration.

Face Match

{
  "check_id": "0c840681-60a8-42bd-9e2a-8fd9f79f612f",
  "session_id": "e4582d65-1bf7-4a70-b71f-cb8e14a15ef9",
  "status": "passed",
  "matched": true,
  "score": 0.91,
  "threshold": 0.8
}

Result Endpoints

Legacy Endpoints

Legacy endpoints remain available for advanced or migration cases, but are not required for session-first integrations.

POST /biometric/liveness/init
POST /biometric/liveness/process
POST /biometric/document/upload-session

Communication APIs

OTP Init

{
  "email": "user@example.com"
}

OTP Confirm

Crypto APIs

Wallet Challenge

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "nonce": "f6f4c8b3-fcb3-4364-91d3-4734c040d5f2",
  "message": "verify.example.com wants you to sign in with your Ethereum account:\n...",
  "expires_at": "2026-04-14T16:55:00.000Z"
}

Wallet Verify

Wallet Reputation

Credential System

Credential Issuance

{
  "credential_id": "0ee1f0fa-1a67-4e19-9893-a32ed00ac70b",
  "credential": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "id": "urn:uuid:0ee1f0fa-1a67-4e19-9893-a32ed00ac70b",
    "type": ["VerifiableCredential", "IdentityVerificationCredential"],
    "issuer": "did:web:nodela.co",
    "credentialSubject": {
      "sessionId": "e4582d65-1bf7-4a70-b71f-cb8e14a15ef9",
      "projectId": 12,
      "trustScore": 0.85,
      "checks": []
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "proofValue": "<BASE64URL_SIGNATURE>"
    }
  },
  "issued_at": "2026-04-14T16:40:10.000Z"
}

Credential Presentation

Credential Shape

Issued credentials include session identifiers, trust score, completed checks, and cryptographic proof so third parties can validate the verification outcome independently.

Webhooks

Webhook Contract

When webhook_url is set during session creation, Nodela sends terminal session events.

Content-Type: application/json
X-Nodela-Signature: sha256=<hex_hmac>

Delivery Behavior

Webhook delivery uses up to 3 attempts with retry backoff. Use webhooks as your primary production source of truth and polling as reconciliation fallback.

Error Handling

Standard Error Shape

{
  "statusCode": 400,
  "message": "Human-readable error message",
  "error": "Bad Request"
}

Auth and Scope Errors

Session and Credential Errors

Redirect & Frontend Integration

Frontend integrations should only open the hosted start_url returned by your backend.

Recommended frontend responsibilities:

• request a session from your backend
• redirect the user to start_url
• handle success and error redirect destinations
• read redirect query params such as session_id and status

Do not:

• embed API keys in frontend code
• open per-check challenge URLs manually
• upload user media directly from your application

Security Best Practices

Status & Lifecycle Reference

Session states:

Check states:

Production Readiness Guide

Recommended operating pattern:

1. register and validate webhook endpoints first
2. treat webhooks as the primary source of truth
3. use polling only for reconciliation and recovery
4. log session IDs and terminal outcomes internally
5. monitor webhook failures and retry behavior

SDK & Integration Examples

The current reference content is API-first. The primary integration template remains:

1. create a session from your backend
2. return start_url to the client
3. consume results with webhooks and session polling endpoints

Migration Guide

Modern integrations should move away from direct media ingestion and per-check orchestration.

Recommended migration path:

1. replace direct biometric upload flows with POST /sessions
2. redirect users to the returned start_url
3. consume final state through webhooks and GET /sessions/:id/status

FAQ