# Table of Contents - [Welcome to DeDi.global | DeDi | NFH Fabric](#welcome-to-dedi-global-dedi-nfh-fabric) - [Developer Platform | NFH Fabric](#developer-platform-nfh-fabric) - [Overview | Beckn Networks | NFH Fabric](#overview-beckn-networks-nfh-fabric) - [Beckn Protocol | Beckn Networks | NFH Fabric](#beckn-protocol-beckn-networks-nfh-fabric) - [Fabric : The value exchange infrastructure | Beckn Networks | NFH Fabric](#fabric-the-value-exchange-infrastructure-beckn-networks-nfh-fabric) - [Setting up the network environment | Beckn Networks | NFH Fabric](#setting-up-the-network-environment-beckn-networks-nfh-fabric) - [Publish Catalogs using CATALG | Beckn Networks | NFH Fabric](#publish-catalogs-using-catalg-beckn-networks-nfh-fabric) - [Onboarding Network Participants | Beckn Networks | NFH Fabric](#onboarding-network-participants-beckn-networks-nfh-fabric) - [Connect to everything using Beckn ONIX | Beckn Networks | NFH Fabric](#connect-to-everything-using-beckn-onix-beckn-networks-nfh-fabric) - [Configuring Network Policies | Beckn Networks | NFH Fabric](#configuring-network-policies-beckn-networks-nfh-fabric) - [Useful links | Beckn Networks | NFH Fabric](#useful-links-beckn-networks-nfh-fabric) - [Developer documentation | DeDi | NFH Fabric](#developer-documentation-dedi-nfh-fabric) - [Use DeDi in your workflows | DeDi | NFH Fabric](#use-dedi-in-your-workflows-dedi-nfh-fabric) - [Signing a single file | Beckn Networks | NFH Fabric](#signing-a-single-file-beckn-networks-nfh-fabric) - [FAQs | DeDi | NFH Fabric](#faqs-dedi-nfh-fabric) - [Build Trusted Networks using REGISTR | Beckn Networks | NFH Fabric](#build-trusted-networks-using-registr-beckn-networks-nfh-fabric) - [Setup for using DeDi APIs | DeDi | NFH Fabric](#setup-for-using-dedi-apis-dedi-nfh-fabric) - [Appendix: Three types of verification | DeDi | NFH Fabric](#appendix-three-types-of-verification-dedi-nfh-fabric) - [DeDi in Verifiable Credential Workflows | DeDi | NFH Fabric](#dedi-in-verifiable-credential-workflows-dedi-nfh-fabric) - [Quickstart | DeDi | NFH Fabric](#quickstart-dedi-nfh-fabric) - [Postman Collection | DeDi | NFH Fabric](#postman-collection-dedi-nfh-fabric) - [Creating and publishing the network manifest | Beckn Networks | NFH Fabric](#creating-and-publishing-the-network-manifest-beckn-networks-nfh-fabric) - [Publish API Performance Benchmarking | Beckn Networks | NFH Fabric](#publish-api-performance-benchmarking-beckn-networks-nfh-fabric) - [DeDi 101 | DeDi | NFH Fabric](#dedi-101-dedi-nfh-fabric) - [Glossary | DeDi | NFH Fabric](#glossary-dedi-nfh-fabric) - [The vision for Decentralised Directory (DeDi) | DeDi | NFH Fabric](#the-vision-for-decentralised-directory-dedi-dedi-nfh-fabric) - [User Guide - DeDi.Global namespace & directory creation | DeDi | NFH Fabric](#user-guide-dedi-global-namespace-directory-creation-dedi-nfh-fabric) - [Watch Feature | DeDi | NFH Fabric](#watch-feature-dedi-nfh-fabric) - [Schema Registry on DeDi | DeDi | NFH Fabric](#schema-registry-on-dedi-dedi-nfh-fabric) - [Features of DeDi.global | DeDi | NFH Fabric](#features-of-dedi-global-dedi-nfh-fabric) - [How to Use DeDi | DeDi | NFH Fabric](#how-to-use-dedi-dedi-nfh-fabric) - [Subscription & Distribution | Beckn Networks | NFH Fabric](#subscription-distribution-beckn-networks-nfh-fabric) - [Representative Use Cases | DeDi | NFH Fabric](#representative-use-cases-dedi-nfh-fabric) - [VC Signing Keys on DeDi | DeDi | NFH Fabric](#vc-signing-keys-on-dedi-dedi-nfh-fabric) - [Domain Verification - The bedrock of trust in DeDi | DeDi | NFH Fabric](#domain-verification-the-bedrock-of-trust-in-dedi-dedi-nfh-fabric) - [Registry Service Performance Benchmarking | Beckn Networks | NFH Fabric](#registry-service-performance-benchmarking-beckn-networks-nfh-fabric) - [Guides | DeDi | NFH Fabric](#guides-dedi-nfh-fabric) - [Revocation Registry on DeDi | DeDi | NFH Fabric](#revocation-registry-on-dedi-dedi-nfh-fabric) - [Public Key Registry on DeDi | DeDi | NFH Fabric](#public-key-registry-on-dedi-dedi-nfh-fabric) - [OpenAPI Specification | DeDi | NFH Fabric](#openapi-specification-dedi-nfh-fabric) - [Creating and publishing Rego policy artifacts | Beckn Networks | NFH Fabric](#creating-and-publishing-rego-policy-artifacts-beckn-networks-nfh-fabric) - [DeDi.global | DeDi | NFH Fabric](#dedi-global-dedi-nfh-fabric) - [Authorized Entity Registry on DeDi | DeDi | NFH Fabric](#authorized-entity-registry-on-dedi-dedi-nfh-fabric) - [API Tools & Resources | DeDi | NFH Fabric](#api-tools-resources-dedi-nfh-fabric) - [Bulk Upload | DeDi | NFH Fabric](#bulk-upload-dedi-nfh-fabric) - [State management | DeDi | NFH Fabric](#state-management-dedi-nfh-fabric) - [Schema design | DeDi | NFH Fabric](#schema-design-dedi-nfh-fabric) - [Catalog Concepts | Beckn Networks | NFH Fabric](#catalog-concepts-beckn-networks-nfh-fabric) - [Delegation Guide | DeDi | NFH Fabric](#delegation-guide-dedi-nfh-fabric) - [Getting started with Beckn | Beckn Networks | NFH Fabric](#getting-started-with-beckn-beckn-networks-nfh-fabric) - [API Reference | DeDi | NFH Fabric](#api-reference-dedi-nfh-fabric) - [State Management | DeDi | NFH Fabric](#state-management-dedi-nfh-fabric) - [Advanced Search | DeDi | NFH Fabric](#advanced-search-dedi-nfh-fabric) - [Delegation Management | DeDi | NFH Fabric](#delegation-management-dedi-nfh-fabric) - [Update Management | DeDi | NFH Fabric](#update-management-dedi-nfh-fabric) - [Lookup Verification | DeDi | NFH Fabric](#lookup-verification-dedi-nfh-fabric) - [How are DeDi.global entries cryptographically secured? | DeDi | NFH Fabric](#how-are-dedi-global-entries-cryptographically-secured-dedi-nfh-fabric) - [Access APIs | DeDi | NFH Fabric](#access-apis-dedi-nfh-fabric) - [Domain Verification | DeDi | NFH Fabric](#domain-verification-dedi-nfh-fabric) - [Publish APIs | DeDi | NFH Fabric](#publish-apis-dedi-nfh-fabric) - [Welcome | Finternet | NFH Fabric](#welcome-finternet-nfh-fabric) - [Find catalogs using DISCOVR | Beckn Networks | NFH Fabric](#find-catalogs-using-discovr-beckn-networks-nfh-fabric) - [How Finternet Compares | Finternet | NFH Fabric](#how-finternet-compares-finternet-nfh-fabric) - [How It Works: The Three Planes | Finternet | NFH Fabric](#how-it-works-the-three-planes-finternet-nfh-fabric) - [Glossary | Finternet | NFH Fabric](#glossary-finternet-nfh-fabric) - [The Actor Model | Finternet | NFH Fabric](#the-actor-model-finternet-nfh-fabric) - [Accounts and Identity | Finternet | NFH Fabric](#accounts-and-identity-finternet-nfh-fabric) - [Policy and Compliance | Finternet | NFH Fabric](#policy-and-compliance-finternet-nfh-fabric) - [Token Operations | Finternet | NFH Fabric](#token-operations-finternet-nfh-fabric) - [Environment Setup | Finternet | NFH Fabric](#environment-setup-finternet-nfh-fabric) - [Programmable Payments | Finternet | NFH Fabric](#programmable-payments-finternet-nfh-fabric) - [Adapter Integration | Finternet | NFH Fabric](#adapter-integration-finternet-nfh-fabric) - [State Modes: Native vs Proxy | Finternet | NFH Fabric](#state-modes-native-vs-proxy-finternet-nfh-fabric) - [Proof Verification | Finternet | NFH Fabric](#proof-verification-finternet-nfh-fabric) - [Event Processing | Finternet | NFH Fabric](#event-processing-finternet-nfh-fabric) - [Manage Supply | Finternet | NFH Fabric](#manage-supply-finternet-nfh-fabric) - [Proxy Tokens | Finternet | NFH Fabric](#proxy-tokens-finternet-nfh-fabric) - [Security Model | Finternet | NFH Fabric](#security-model-finternet-nfh-fabric) - [Architecture | Finternet | NFH Fabric](#architecture-finternet-nfh-fabric) --- # Welcome to DeDi.global | DeDi | NFH Fabric ### [](https://docs.nfh.global/dedi#quick-navigation) 🎯 Quick Navigation [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart) ![Cover](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1636056514473-dd532ed74cf2%3Fcrop%3Dentropy%26cs%3Dsrgb%26fm%3Djpg%26ixid%3DM3wxOTcwMjR8MHwxfHNlYXJjaHw3fHxzdGFydHxlbnwwfHx8fDE3NzQ5NzQzNTN8MA%26ixlib%3Drb-4.1.0%26q%3D85&width=490&dpr=3&quality=100&sign=3c4900ee&sv=2) **πŸš€ Quick Start** Create namespaces, publish directories, and manage records in minutes ![Cover](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1605379399642-870262d3d051%3Fcrop%3Dentropy%26cs%3Dsrgb%26fm%3Djpg%26ixid%3DM3wxOTcwMjR8MHwxfHNlYXJjaHwyfHxkZXZlbG9wZXJ8ZW58MHx8fHwxNzc1MDMzODc1fDA%26ixlib%3Drb-4.1.0%26q%3D85&width=490&dpr=3&quality=100&sign=a73e7c43&sv=2) **πŸ’» Developer docs** Integration guides and API reference for building on DeDi [](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi) ![Cover](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2Fimages.unsplash.com%2Fphoto-1525542922656-fb22d0a7961f%3Fcrop%3Dentropy%26cs%3Dsrgb%26fm%3Djpg%26ixid%3DM3wxOTcwMjR8MHwxfHNlYXJjaHwxfHxwaG9uZWJvb2t8ZW58MHx8fHwxNzc1MDMzOTQ0fDA%26ixlib%3Drb-4.1.0%26q%3D85&width=490&dpr=3&quality=100&sign=80c33223&sv=2) **πŸ“– The vision for DeDi** Understand the protocol, vision, and verification models * * * ### [](https://docs.nfh.global/dedi#resources) πŸ”— Resources * 🌐 **Platform:** [dedi.global](https://dedi.global/) * πŸ™ **GitHub:** [dedi-global](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol) * πŸ“§ **Support:** [Get Help](https://docs.google.com/forms/d/e/1FAIpQLSesBZMkgmnKY3SDzGQPDF8E-OoAo75O5n4LVrdoDKFtz_Y3FA/viewform) * * * globe-pointer _Operated by_ [_Networks for Humanity Foundation_](https://networksforhumanity.org/) _Β· Built on DDP under_ [_Linux Foundation Decentralized Trust_](https://lf-decentralized-trust-labs.github.io/labs/lfdt/decentralized-directory-dedi.html) [NextUse DeDi in your workflows](https://docs.nfh.global/dedi/about/use-dedi-in-your-workflows) Last updated 1 month ago Was this helpful? --- # Developer Platform | NFH Fabric [](https://docs.nfh.global/#nfh-fabric) NFH Fabric ------------------------------------------------------- The Value Exchange Infrastructure Networks for Humanity (NFH) is a global network of non-profit labs founded by technologists with unparalleled experience in building universal digital infrastructure at population scale. [](https://dedi.global/) ![Cover](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FYW7CIBnOuw9ClF3St0uJ%2Fblobs%2FbDDCOCb68Xj6TqgGBRT3%2Fno-code.jpg&width=490&dpr=3&quality=100&sign=29329bd5&sv=2) #### [](https://docs.nfh.global/#undefined) **DeDi Registry** Establishing Trust by verifying the integrity, validity, and authenticity [](https://docs.beckn.io/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg) ![Cover](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FYW7CIBnOuw9ClF3St0uJ%2Fblobs%2FVwkiWDpRvOaKY4U2K8NW%2Fhosted.jpg&width=490&dpr=3&quality=100&sign=8bcafa41&sv=2) #### [](https://docs.nfh.global/#undefined-1) **Beckn CATALG** Shared catalogue publication and syndication for Beckn networks [](https://docs.nfh.global/finternet-docs) ![Cover](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FYW7CIBnOuw9ClF3St0uJ%2Fblobs%2F7y7hERQyUDdTySApkD0O%2Fapi-reference.jpg&width=490&dpr=3&quality=100&sign=54a0b43f&sv=2) #### [](https://docs.nfh.global/#undefined-2) **UNITS** Manage tokenised digital assets for transfer and ledger enforcements [](https://docs.nfh.global/#join-a-community-of-thousands-of-developers) Join a community of thousands of developers ------------------------------------------------------------------------------------------------------------------------- Join our community in just a few steps. [](https://github.com/Networks-for-Humanity) **NFH Community** Join our Github community to post questions, get help, and share resources with over 3,000 like-minded developers. [https://github.com/Networks-for-Humanity](https://github.com/Networks-for-Humanity) [](https://github.com/beckn/) **Beckn Community** Join our Beckn Community on Github to contribute to NFH Fabric services such as Registry, Catalg, ONIX and more. [https://github.com/beckn](https://github.com/beckn) Last updated 1 month ago Was this helpful? --- # Overview | Beckn Networks | NFH Fabric The Internet made information fluid; the next wave will make value fluid. [Beckn](https://becknprotocol.io/) is an open protocol that enables people, organisations, and AI systems to discover, contract, and exchange value directly, without intermediaries. Where HTTP unified information exchange, **Beckn Protocol defines a composable language for** _**value exchange**_ using discovery, contracting, negotiation, fulfilment, and post-fulfilment as interoperable digital primitives. Created by the architects of India’s population-scale digital public infrastructure - Aadhaar (1.4 billion digital IDs, 90 million authentications daily) and UPI (20 billion transactions monthly) - Beckn extends that vision to enable open, peer-to-peer value exchange across commerce, mobility, finance, energy, and beyond. Beckn’s growth is exponential: **300Mn+ digital commerce orders**, **125Mn+ zero-commission rides**, **hundreds of thousands of digital loans**, and **tens of megawatt-hours traded daily** on open energy grids ([DEG](https://energy.becknprotocol.io/) , [UEI](https://ueialliance.org/) ). The same protocol now powers networks in **education & skilling** ([ONEST](https://onest.network/) )**, health** ([UHI](https://abdm.gov.in/UHI/product-overview) )**, and agriculture** ([OpenAgriNet](https://openagrinet.global/) , [VISTAAR](https://vistaar.da.gov.in/) ), a blueprint for interoperable economies. Many of the world’s toughest challenges - energy reliability, healthcare access, sustainable mobility, agricultural resilience β€” are, at their core, also problems of coordination among countless independent actors who must operate under shared trust. Beckn enables institutions, enterprises, and communities to exchange value transparently, scaling collaboration without central control. Across energy, health, agriculture, and mobility, Beckn networks demonstrate how open standards strike a balance between efficiency and equity, replacing centralised intermediaries with verifiable, peer-to-peer coordination. The result is a new kind of infrastructure: resilient, transparent, and innovation-friendly. Take energy, for example. Beckn’s **Digital Energy Grid** connects AI and clean powerβ€”turning fragmented, distributed assets into [**self-organising, digital energy ecosystems**.](https://youtu.be/o4lFYuhSIZM?si=7Lyktap3duL43WGU) It relieves grid stress while aligning AI’s rising energy demand with sustainable generation, coordinating digital workloads and physical resources so that computation grows responsibly. All Beckn-based networks are now converging onto Beckn **Fabric** - a universal, agentic, open rails for moving value beyond money (akin to global card networks, but open for moving value beyond money). Operating as shared runtime rails, Beckn One enables humans, businesses, communities, governments and their AI agents to publish, discover, contract and exchange value seamlessly across domains. Beckn is designed for value exchange at a population scale. Its core propertiesβ€”openness, verifiability, and composabilityβ€”apply equally to both autonomous agents and non-autonomous agents. The alignment between Beckn and frameworks like the MCP suggests a path toward open networks for coordinating economic transactions across people, businesses, communities, and their millions of agents. [](https://docs.nfh.global/beckn#links) Links -------------------------------------------------- **Beckn Protocol** - [spec repo](https://github.com/beckn/protocol-specifications-v2) **Beckn Schemas** - [schema specs](https://schema.beckn.io/) **Beckn Registry** - [Dedi.global](https://dedi.global/) **Beckn ONIX** - [Github repo](https://github.com/beckn/beckn-onix) [NextBeckn Protocol](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol) Last updated 1 month ago Was this helpful? Was this helpful? --- # Beckn Protocol | Beckn Networks | NFH Fabric [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#introduction) Introduction ----------------------------------------------------------------------------------------------------- The Beckn Protocol specification defines a standard protocol stack that allows independently run applications to take part in trusted value exchange transactions. These transactions usually move through discovery, contracting, fulfillment, and post-fulfillment. This document explains Beckn v2 at a high level. It is an overview. It is meant to help a human or an AI agent understand how the parts fit together before going into the full API files and schema files. This protocol stack consists of the following layers (bottom to top) 1. Network Architecture 2. API Specification 3. Composable linked-data schema 4. Communication Protocol 5. Workflows Let us understand each of these layers briefly. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#network-architecture) Network Architecture A Beckn network is a set of separate platforms. Each platform is run independently. The protocol gives them a common way to talk to each other. In Beckn v2 the main actor roles are the following: 1. BAP (Beckn Application Platform) - the buyer side or user side platform 2. BPP (Beckn Provider Platform) - the seller side or provider side platform 3. CS (Catalog Service) - the service that receives catalog publications from BPPs 4. DS (Discovery Service) - the service that answers discovery queries from BAPs 5. Registry - the trust directory that stores participant identity, endpoints, and public keys A BAP discovers supply through a DS. A BPP publishes its catalog to a CS. After discovery, the BAP usually talks directly to the BPP for the transaction. All actors use the Registry to find endpoints and public keys and to verify signatures. In Beckn v2 the Registry is a DeDi-compliant directory. This means the trust layer is treated as a proper public directory and not as a custom side system. The important point is this: Beckn v2 does not depend on a live multicast gateway for discovery. Discovery is catalog-first and index-based. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#api-specification) API Specification The API specification defines the common shape of Beckn messages and endpoints. In Beckn v2, the endpoint pattern is simple: For example, a participant may expose endpoints such as: * `/beckn/discover` * `/beckn/on_discover` * `/beckn/select` * `/beckn/on_select` * `/beckn/confirm` * `/beckn/on_confirm` The exact actions a participant supports depend on its role. Every Beckn API call carries a transport envelope and a business payload. The transport envelope is the fixed part of the protocol. It carries things like the action name, IDs, time, and routing data. The business payload is the domain data inside the message. Fields such as `context`, `message`, `inReplyTo`, `status`, and signatures belong to the transport contract. They are fixed. They must not be renamed or redefined by domain schema. At a high level, the main action groups are: 1. Discovery - `discover`, `on_discover` 2. Contracting - `select`, `on_select`, `init`, `on_init`, `confirm`, `on_confirm` 3. Fulfillment - `status`, `on_status`, `update`, `on_update`, `track`, `on_track`, `cancel`, `on_cancel` 4. Post-fulfillment - `rate`, `on_rate`, `support`, `on_support` 5. Infrastructure - `publish` and Registry lookups ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#composable-linked-data-schema) Composable linked-data schema In Beckn v2, the business payload is not just plain JSON. It is JSON-LD. JSON-LD lets every type and field carry a shared meaning. It does this mainly through two ideas: * `@context` - tells the reader where the meaning of terms comes from * `@type` - tells the reader what kind of object it is This is important because Beckn is meant to work across domains, geographies, and networks. A machine should not only read the data. It should also understand what the data means. Beckn v2 separates schema into three layers: 1. The transport envelope layer - the API envelope and container schemas 2. The core schema layer - shared business types such as `Catalog`, `Item`, `Offer`, `Intent`, `Contract`, `Provider`, `Fulfillment` 3. The domain schema pack layer - domain specific extensions such as retail, mobility, health, logistics, and others Where possible, Beckn maps types and fields to schema.org. When Beckn needs its own meaning, it uses the Beckn namespace. This gives global interoperability without losing Beckn-specific meaning. This layered design solves an important problem. The transport API can stay small and stable. At the same time, the business schema can grow over time. New domains can be added without changing the basic transport contract. The `schema.beckn.io` website is the public place where these schema resources can be published and browsed. It gives stable IRIs, JSON-LD contexts, RDF vocabularies, and versioned schema pages. In simple words, it is the public map of meaning for Beckn data. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#communication-protocol) Communication Protocol The communication protocol defines how Beckn messages move over the network. At the transport level, Beckn v2 uses HTTPS and digital signatures. There are three main request modes: 1. POST - used for normal forward requests and callbacks 2. GET Body Mode - used when a GET request with a JSON body is allowed 3. GET Query Mode - used when the whole request must fit inside a URL, such as a QR code or a deep link Every request except GET Query Mode carries a Beckn Signature in the `Authorization` header. The receiver verifies that signature using the sender's public key from the Registry. The communication pattern is usually as follows: 1. The sender sends a signed request 2. The receiver immediately returns `Ack` or `Nack` 3. If the request is accepted, the business result usually comes later as a callback 4. The callback carries `inReplyTo` so it can be tied to the original request 5. The `Ack` carries a `counterSignature`, which works as a signed receipt This means Beckn is not just request-response in the usual web sense. It is mainly an asynchronous and event-driven protocol. At a practical level, Beckn supports all of the following patterns: * **Same-session acknowledgement** - the receiver immediately says whether it received the message * **Asynchronous business response** - the actual business result comes later through a callback * **Synchronous business response in some cases** - for example, discovery results may also be returned synchronously depending on network policy * **Later state-driven messages** - a later message may be sent because the state changed, not because a user clicked a button at that moment GET Query Mode is a special case. It is used when the request must be a self-contained URL. In that mode, the server must not send an asynchronous callback. It only returns an acknowledgement. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#workflows) Workflows Workflows are the business paths built on top of the API actions. The protocol gives reusable actions. A network then combines those actions into a workflow. A simple Beckn workflow often looks like this: 1. A BPP publishes catalog data 2. A BAP discovers that catalog through a DS 3. The BAP starts a transaction with a BPP 4. The BAP and BPP agree on terms 5. The BPP fulfills the contract 6. The parties may exchange rating or support information later Not every network uses every action. Not every domain needs every step. The protocol gives the building blocks. The network chooses the path. [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#understanding-the-beckn-api-specification) Understanding the Beckn API Specification --------------------------------------------------------------------------------------------------------------------------------------------------------------- This section gives the Beckn API picture at a level useful for implementation. It keeps the discussion short and clear. A separate document can go action by action in more detail. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#what-changed-in-beckn-v2) What changed in Beckn v2 If you have seen older Beckn material, these are the changes that matter most: 1. Discovery is no longer based on live gateway multicast. BPPs publish catalogs to the Catalog Service. BAPs discover through Discovery Service. 2. The API surface is simplified around the common endpoint pattern `/beckn/{becknEndpoint}`. 3. The transport contract and the business schema are now clearly separated. 4. The business payload is JSON-LD, with shared meaning through `@context` and `@type`. 5. The Registry is aligned to a DeDi-compliant directory model. 6. Non-repudiation is stronger because acknowledgements can carry `counterSignature` and callbacks can carry `inReplyTo`. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#what-a-beckn-network-participant-must-do) What a Beckn network participant must do Any platform can take part in a Beckn network if it can do the following: 1. Register its identity, endpoint, and public keys in the Registry 2. Send signed Beckn messages 3. Verify signed Beckn messages from others 4. Implement the endpoints needed for its role 5. Read and produce the shared JSON-LD payloads ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#the-main-actors) The main actors Let us look at the main actors one by one. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#bap) BAP A BAP is the buyer side platform. It is the platform where the user, buyer, or demand side experience lives. A BAP usually does the following: 1. Sends discovery requests to a DS 2. Receives discovery results 3. Sends transaction requests to BPPs 4. Receives callbacks from BPPs 5. Shows the results to the end user #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#bpp) BPP A BPP is the provider side platform. It is the platform where the provider's catalog, pricing, contract logic, and fulfillment logic live. A BPP usually does the following: 1. Publishes its catalog to a CS 2. Receives transaction requests from BAPs 3. Sends callbacks to BAPs 4. Updates contract and fulfillment state over time #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#cs-catalog-service) CS (Catalog Service) A CS is the catalog publishing service. It receives catalog publications from BPPs, validates them, normalizes them, and prepares them for indexing. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#ds-discovery-service) DS (Discovery Service) A DS is the catalog discovery service. It keeps an index of published catalog data and answers discovery requests from BAPs. This is why Beckn v2 discovery is fast and does not need live fan-out to all BPPs. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#registry) Registry The Registry is the trust directory of the network. It stores participant records, endpoints, capabilities, and public keys. Before a participant sends a message, it can use the Registry to find where to send the message and how to verify the signature. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#what-every-beckn-packet-contains) What every Beckn packet contains Every Beckn request or callback contains two main parts: * `context` * `message` The `context` carries the routing and control data. The `message` carries the business data. A callback also carries `inReplyTo` so that it can be tied to the original request. A simplified Beckn packet looks like this: The important thing to remember is this: the transport envelope and the business payload are different concerns. * The transport envelope tells you how the message should move * The business payload tells you what the message means ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#transport-envelope-and-business-payload) Transport envelope and business payload Beckn v2 keeps these two layers separate on purpose. The transport layer gives a stable message frame. It defines the container schemas such as `Context`, `RequestContainer`, `CallbackContainer`, `Ack`, `Nack`, `CounterSignature`, and `InReplyTo`. The business layer gives the actual domain objects such as `Catalog`, `Item`, `Offer`, `Intent`, `Contract`, `Fulfillment`, `Tracking`, `Rating`, and `Support`. This separation has a big benefit. The transport layer stays stable. The business layer can evolve across domains. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#a-note-on-v2-words) A note on v2 words In older Beckn explanations, you will often see the word `Order`. In Beckn v2 core schema, the more exact word is `Contract`. The idea is similar. It is the formal record of what the parties agreed to. In the same way, `ContractItem` replaces the older `OrderItem`. This matters mainly at the schema layer. The transaction idea itself remains easy to understand: discovery leads to agreement, agreement leads to fulfillment, and fulfillment may be followed by support or rating. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#the-main-request-modes) The main request modes The same Beckn action can be carried in different transport modes. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#post) POST POST is the normal mode for: * forward requests such as BAP to DS or BAP to BPP * callbacks such as DS to BAP or BPP to BAP #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#get-body-mode) GET Body Mode GET Body Mode lets a caller send a Beckn request in a GET request with a JSON body. This is useful in cases where GET semantics are needed but the caller can still send a body and expects a later callback. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#get-query-mode) GET Query Mode GET Query Mode puts the full request and signature inside the URL query string. This is useful for: * QR codes * deep links * bookmarkable search links * simple browser or device clients In GET Query Mode there is no asynchronous callback. The server only returns an `Ack` or a `Nack`. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#how-discovery-works-in-beckn-v2) How discovery works in Beckn v2 Discovery is one of the biggest changes in Beckn v2. In older models, discovery often depended on a gateway sending the query to many BPPs in real time. In Beckn v2, discovery is catalog-first. 1. A BPP publishes catalog updates to a CS 2. The CS validates and normalizes the data 3. The CS forwards the data to a DS 4. The DS indexes the catalog data 5. A BAP sends a `discover` request to the DS 6. The DS returns matching catalog data 7. After discovery, the BAP talks directly to the chosen BPP This design gives three major benefits: 1. Discovery becomes faster 2. BPPs do not need to answer every live discovery query 3. Catalog publication and catalog search can scale separately ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#the-main-action-groups) The main action groups The Beckn actions are best understood by stage. Stage Main actions What they do Discovery `discover`, `on_discover` Find matching catalog data Contracting `select`, `on_select`, `init`, `on_init`, `confirm`, `on_confirm` Agree on scope, terms, price, and create the contract Fulfillment `status`, `on_status`, `update`, `on_update`, `track`, `on_track`, `cancel`, `on_cancel` Manage the live state of the contract Post-fulfillment `rate`, `on_rate`, `support`, `on_support` Handle rating and support Infrastructure `publish`, Registry lookups Publish supply and resolve trust data A simple way to think about these stages is: 1. **Discovery** - find what is available 2. **Contracting** - agree what will happen 3. **Fulfillment** - do what was agreed 4. **Post-fulfillment** - rate, support, and close the loop ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#a-full-beckn-flow-at-a-glance) A full Beckn flow at a glance Not every transaction uses every step. For example, some networks may not use `track`. Some domains may not need `support`. Some contracts may not change after confirmation, so `update` may never be used. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#what-an-implementer-should-build) What an implementer should build If you want to start implementing Beckn, it helps to think role by role. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#if-you-are-building-a-bap) If you are building a BAP You usually need to build the following: 1. A client for calling DS and BPP endpoints 2. Callback endpoints for receiving `on_` actions 3. Registry lookup support 4. Message signing and signature verification 5. JSON-LD payload handling 6. Contract and fulfillment state management on the buyer side #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#if-you-are-building-a-bpp) If you are building a BPP You usually need to build the following: 1. Catalog publication to a CS 2. Request endpoints for transaction actions 3. Callback sending to BAPs 4. Registry registration and key publication 5. Message signing and signature verification 6. Contract, payment, and fulfillment logic on the provider side #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#if-you-are-building-a-catalog-service) If you are building a Catalog Service You need to build: 1. A `publish` endpoint 2. Catalog validation and normalization 3. Deduplication and merge logic 4. Forwarding of normalized catalog graphs to one or more DS instances #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#if-you-are-building-a-discovery-service) If you are building a Discovery Service You need to build: 1. A `discover` endpoint 2. An index for `Catalog`, `Item`, `Offer`, and related graphs 3. Ranking, filtering, and query logic 4. Callback or synchronous response handling as allowed by the network policy #### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#if-you-are-building-any-beckn-actor) If you are building any Beckn actor You should also remember the following: 1. Use HTTPS 2. Verify signatures on every incoming message 3. Use the Registry for public key resolution 4. Treat the transport envelope as fixed 5. Treat the `message` as the business payload 6. Load JSON-LD contexts in a controlled way. Do not trust unknown remote contexts blindly. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#summary) Summary Beckn v2 becomes easy to understand once the separation of concerns is clear. * The **network architecture** tells you who talks to whom * The **API specification** tells you what endpoint and packet shape to use * The **linked-data schema** tells you what the payload means * The **communication protocol** tells you how signed requests, acknowledgements, and callbacks move * The **workflows** tell you how the actions are combined for a real business journey At a practical level, Beckn v2 works like this: 1. Providers publish catalog data 2. Discovery services index that data 3. Buyer side platforms discover matching supply 4. Buyer and provider platforms agree on terms 5. The provider fulfills the contract 6. The parties may exchange rating or support data after that If you understand these six ideas, you can start reading the Beckn transport files, schema files, and network guides with the right mental model. [PreviousOverview](https://docs.nfh.global/beckn) [NextFabric : The value exchange infrastructure](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure) Last updated 1 month ago Was this helpful? * [Introduction](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#introduction) * [Network Architecture](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#network-architecture) * [API Specification](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#api-specification) * [Composable linked-data schema](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#composable-linked-data-schema) * [Communication Protocol](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#communication-protocol) * [Workflows](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#workflows) * [Understanding the Beckn API Specification](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#understanding-the-beckn-api-specification) * [What changed in Beckn v2](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#what-changed-in-beckn-v2) * [What a Beckn network participant must do](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#what-a-beckn-network-participant-must-do) * [The main actors](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#the-main-actors) * [What every Beckn packet contains](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#what-every-beckn-packet-contains) * [Transport envelope and business payload](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#transport-envelope-and-business-payload) * [A note on v2 words](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#a-note-on-v2-words) * [The main request modes](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#the-main-request-modes) * [How discovery works in Beckn v2](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#how-discovery-works-in-beckn-v2) * [The main action groups](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#the-main-action-groups) * [A full Beckn flow at a glance](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#a-full-beckn-flow-at-a-glance) * [What an implementer should build](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#what-an-implementer-should-build) * [Summary](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol#summary) Was this helpful? GitBook AssistantAskCopy /beckn/{becknEndpoint} GitBook AssistantAskCopy { "context": { "domain": "beckn:retail", "action": "discover", "version": "2.0.0", "bapId": "bap.example.com", "bapUri": "https://bap.example.com/callback", "transactionId": "txn-123", "messageId": "msg-456", "timestamp": "2026-03-27T00:00:00Z", "ttl": "PT30S" }, "message": { "@context": [\ "https://schema.org/",\ "https://schema.beckn.io/core/v2.0/context.jsonld"\ ], "@type": "Intent" } } --- # Fabric : The value exchange infrastructure | Beckn Networks | NFH Fabric Fabric is a suite of cloud-based, reusable, standards-aligned infrastructure services designed to support open, multi-participant digital networks. These services provide a thin operational layer on top of traditional cloud infrastructure, helping Network Facilitators focus on governance and sector design, while also enabling Network Participantsβ€”such as BAPs, BPPs, logistics providers, and third-party service operatorsβ€”to participate more easily, consistently, and securely across one or more Beckn-aligned networks. Each Fabric service is independent, composable, and can be adopted incrementally. Network Facilitators can choose to adopt or extend these services for network-wide utility, while Network Participants can use them locally to simplify integration, reduce engineering overhead, and ensure predictable compliance with Beckn Protocol. The key Beckn services are described in this section. [PreviousBeckn Protocol](https://docs.nfh.global/beckn/introduction-to-beckn/beckn-protocol) [NextPublish Catalogs using CATALG](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg) Last updated 1 month ago Was this helpful? Was this helpful? --- # Setting up the network environment | Beckn Networks | NFH Fabric This section covers how a Network Facilitator Organization (NFO) sets up a new Beckn network using the Beckn Registry infrastructure on DeDi Global, and how approved Network Participants (NPs) are onboarded into that network. A Beckn network is anchored by a verified namespace and one or more registries under that namespace. Together, the namespace and registry form the network's root of trust and define the network boundary that participants can use during signing, verification, and discovery. ### [](https://docs.nfh.global/beckn/creating-an-open-network/setting-up-the-network-environment#registering-the-network-on-beckn-fabric) Registering the network on Beckn fabric To register a new Beckn network, the NFO first creates its identity root on [DeDi Global](https://publish.dedi.global/) and then publishes a registry for the network. This registry becomes the canonical place from which participants in that network are referenced. Dedi.global is a ready to use SaaS implementing the open [DeDi protocol](https://github.com/LF-Decentralized-Trust-labs/DeDi) offered by the Network for Humanity Foundation. This allows registrars to effortlessly publish and manage their directories (aka public registries) on a decentralized, user controlled infrastructure. #### [](https://docs.nfh.global/beckn/creating-an-open-network/setting-up-the-network-environment#what-this-establishes) What this establishes * A verified identity for the NFO, anchored to its domain * A registry that represents the network * A network\_id that participants can rely on for trust and policy enforcement The network\_id is of the form: GitBook AssistantAskCopy / For example: GitBook AssistantAskCopy example-nfo.com/commerce-network lightbulb **Tip**: If you operate across multiple environments such as sandbox, staging, and production, create a separate registry for each environment. If needed, you can also create separate registries per sector. This keeps network boundaries explicit and allows participants to configure their ONIX instances appropriately to allow requests from networks they want to interact with. NFOs are free to create these boundaries as per their operational requirements. #### [](https://docs.nfh.global/beckn/creating-an-open-network/setting-up-the-network-environment#step-1-set-up-a-dedi-global-account) Step 1: Set up a DeDi Global account Create an account on [DeDi Global](https://publish.dedi.global/) . #### [](https://docs.nfh.global/beckn/creating-an-open-network/setting-up-the-network-environment#step-2-create-and-verify-the-nfo-namespace) Step 2: Create and verify the NFO namespace 1. Create a namespace in DeDi. 2. Request for whitelisting of a domain. This can be done [here](https://docs.google.com/forms/d/e/1FAIpQLScAwEZh94DCIw70zrxWUJ1cud_wYfo_WEjqDpEmbxaw5ZF9aw/viewform) . The request will be processed within 5 minutes, provided no adverse signals are detected for the domain. 3. Enter the domain name. A TXT record will be generated (only for whitelisted domains). 4. Copy the generated TXT record as it needs to be updated in the DNS configuration file of your domain. 5. Click β€œVerify” after you have successfully updated the domain’s DNS file. The DNS text propagation will take from 15 min to up to 48 hours. Once this is done, your domain is verified. Example: If you as an NFO operate example-nfo.com, your namespace will be anchored to that domain. #### [](https://docs.nfh.global/beckn/creating-an-open-network/setting-up-the-network-environment#step-3-create-the-network-registry) Step 3: Create the network registry Inside the verified namespace, create a new registry using the Beckn subscriber reference schema. This registry stores references to the NPs that belong to the network. The registry name is significant because it becomes part of the network\_id. For example, an NFO registry named commerce-network under example-nfo.com results in the network ID example-nfo.com/commerce-network. lightbulb Tip: You can create multiple registries for any number of boundaries that you want to create in the fabric. Based on your operational requirements you can create separate registries for specific environments or sectors that you are operating in. Example: Suppose your verified domain is `example-nfo.com` * Sandbox environment: Registry name: `sandbox` Network ID: `example-nfo.com/sandbox` * Staging environment: Registry name: `staging` Network ID: `example-nfo.com/staging` * Production environment: Registry name: `production` Network ID: `example-nfo.com/production` * Sector-specific production environment: Registry name: `mobility-production` Network ID: `example-nfo.com/mobility-production` Each network registry should eventually contain references to approved participants, with valid subscriber details, callback endpoints, and public-key material published by those participants in their own registries. [PreviousGetting started with Beckn](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn) [NextOnboarding Network Participants](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants) Last updated 1 month ago Was this helpful? Was this helpful? --- # Publish Catalogs using CATALG | Beckn Networks | NFH Fabric **Beckn CATALG** is the shared catalog publication and distribution service of the Beckn ecosystem. Providers publish their catalogs to CATALG once, and CATALG validates them and pushes them out to every Discovery Service subscribed to that network. This page tells you what CATALG does and how it fits into a Beckn network. When you are ready to send your first publish request, jump to the [Quickstart](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/quickstart) . * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#the-problem) The problem ----------------------------------------------------------------------------------------------------------------------------------------------------------- Without a shared catalog backbone, Beckn networks fragment quickly: * Every provider publishes through a different mechanism * Discovery Services maintain stale, inconsistent copies of the same data * There is no network-wide view of what is live, valid, or active * Every provider reinvents product definitions independently The result is duplicated effort, inconsistent search results, and no canonical source of truth. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#what-catalg-does) What CATALG does --------------------------------------------------------------------------------------------------------------------------------------------------------------------- CATALG sits between **Provider Nodes** (the participants that publish catalogs) and **Discovery Services** (the search layer that consumer applications query). It gives the network: * **One place to publish** β€” every catalog flows through a single validated pipeline * **Automatic distribution** β€” every accepted catalog is pushed to all subscribed Discovery Services within seconds * **Schema-aware validation** β€” catalogs are checked against the Beckn v2.0 schema and any domain overlays before acceptance * **Network-wide templates** β€” a network can publish canonical resource definitions that providers extend, ensuring data consistency across the network * **Granular visibility control** β€” publishers can restrict delivery to specific network participants CATALG is not a query engine. It is the **source of truth** for what is published. Consumer applications never call CATALG directly β€” they query a Discovery Service, which keeps its data current by subscribing to CATALG. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#high-level-architecture) High-Level Architecture ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ![](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2F3638162302-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMnBHMPqabDZYD3t20Ocv%252Fuploads%252Fgit-blob-31b421e3f8956792862278f521b0fbcbb53523c0%252FBecknCatalg.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=b8a64431&sv=2) Beckn CATALG Architecture * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#how-it-works-end-to-end) How it works end-to-end ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The full lifecycle β€” from a Discovery Service setting up its subscription, through a network publishing master templates, to a provider publishing a real catalog and a consumer discovering it: **Key points:** * **Subscription is synchronous** β€” CATALG returns `subscriptionId` and `status: ACTIVE` directly in the 200 OK response * **Publish ACK is synchronous** β€” returned immediately once the request passes authorization and schema checks * `**on_publish**` **is asynchronous** β€” notifies the publisher of the per-catalog result (ACCEPTED / REJECTED / PARTIAL) * `**catalog/push**` **is synchronous** β€” CATALG POSTs to each matching Discovery Service and receives an immediate ACK or NACK; delivered only when the catalog is ACCEPTED or PARTIAL * `**on_discover**` **is asynchronous** β€” Discovery Service calls the Consumer Node's `bapUri` with matching results * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#where-you-fit) Where you fit --------------------------------------------------------------------------------------------------------------------------------------------------------------- You are… Start here A **Provider Node** publishing catalogs [Quickstart](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/quickstart) β€” publish your first catalog A **Discovery Service builder** receiving catalogs [Subscription & Distribution](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution) A **Network Facilitator** defining templates [Catalog Concepts β†’ Catalog types](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#catalog-types) Just looking up an endpoint [API Reference](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/api-reference) * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#example-use-case) Example use case --------------------------------------------------------------------------------------------------------------------------------------------------------------------- A multi-brand EV charging network wants to list all its charging stations nationwide. The network facilitator first publishes a **master (template) catalog** defining canonical charging resource schemas β€” connector types, power levels, tariff structures. Each charging operator then publishes a **REGULAR catalog** extending the master templates, adding their specific stations, live availability, and pricing. CATALG validates every submission and automatically pushes accepted catalogs to all subscribed Discovery Services. One such Discovery Service β€” Beckn DISCOVR β€” makes the data available for discovery. A mobility app queries DISCOVR for "CCS2 chargers above 50 kW near Bangalore" and gets real-time results from multiple operators in a single response. * * * **Next:** [Quickstart β€” Publish Your First Catalog β†’](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/quickstart) [PreviousFabric : The value exchange infrastructure](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure) [NextQuickstart](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/quickstart) Last updated 9 days ago Was this helpful? * [The problem](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#the-problem) * [What CATALG does](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#what-catalg-does) * [High-Level Architecture](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#high-level-architecture) * [How it works end-to-end](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#how-it-works-end-to-end) * [Where you fit](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#where-you-fit) * [Example use case](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg#example-use-case) Was this helpful? --- # Onboarding Network Participants | Beckn Networks | NFH Fabric ### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#adding-or-onboarding-network-participants) Adding or onboarding Network Participants Once the network registry has been created, approved NPs can be added to the network. In this model, the NFO does not duplicate participant data manually. Instead, the NFO adds references to NP-owned registries or NP-owned records that are already published on DeDi Global. This preserves self-owned identity for participants while allowing the NFO to curate who belongs to the network. #### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#adding-registry-entries) Adding Registry entries For each approved NP, create a subscriber reference record in the network registry. The NP details should already be publised by the NP on the fabric and the steps for the same can be found [here](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#network-participants-registering-on-the-fabric) . These records tell the network which NP-owned registry or record should be treated as part of the network. **Fields required in the network registry entry** **Field** **Description** **Example** subscriber\_id The NP's unique identifier example-bap.com url Lookup URL of the NP registry or NP record on DeDi Global https://api.dedi.global/dedi/lookup/... type Whether the URL points to a full registry or an individual record Registry, Record **Choosing between type Registry or Record** * Use Registry when the entire NP registry should be recognized as belonging to the network. This means all current and future records inside that NP registry are treated as part of the network. * Use Record when only one specific NP record should belong to the network. **Getting the Lookup URL of the NP** To get the lookup URL of a record or a registry of an NP, you can go to the [dedi explore page](https://explore.dedi.global/) and find the namespace of the NP. * Click on the NP namespace to see all their registries. * Click on the registry that needs to be added. Please note it should have the registry tag as beckn\_subscriber. ![](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2F3638162302-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMnBHMPqabDZYD3t20Ocv%252Fuploads%252Fgit-blob-42897ea3c47168dd381339375df34ee366b40d09%252Funknown%2520%283%29.png%3Falt%3Dmedia&width=300&dpr=3&quality=100&sign=47bd013a&sv=2) * Once inside the registry, if you need to reference the whole registry, click on Copy in the Registry Lookup API widget to copy the URL. If you are providing the registry lookup URL, then type should be Registry. * If you want to reference a single record in the registry as belonging to your network, click on the record from the list of records in the registry. * Once inside the record, click on Copy in the Record Lookup API widget to copy the URL. ![](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2F3638162302-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMnBHMPqabDZYD3t20Ocv%252Fuploads%252Fgit-blob-af4161e39518ebc99fc4aa58ac1f8f81e259bcc3%252Fimage%2520%281%29.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=2e1541d6&sv=2) Please note the details of the NP will be visible on DeDi explore only if they have verified their namespace. **What the NFO should validate before adding an NP** Before creating the reference entry, confirm that: * the NP has published its subscriber details under its own verified namespace * the published callback URL is correct and reachable * the published public key is valid for signing and verification * the role and participant details are appropriate for the network * the NP is being added to the correct environment-specific registry Once this reference entry is added, that NP becomes part of the curated network represented by the NFO's network\_id. [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#network-participants-registering-on-the-fabric) Network Participants registering on the fabric --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This section is for Network Participants (NPs) such as BAPs and BPPs that want to join an existing Beckn network. To participate, an NP must first publish its subscription and key details on the Beckn Registry infrastructure, and then configure its Beckn ONIX instance to transact on the network. In this model, the NP owns and publishes its identity under its own verified domain, while the Network Facilitator Organization (NFO) decides whether to include that NP in a curated network. ### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#id-4.1-registering-your-subscription-details-on-beckn-fabric) 4.1 Registering your subscription details on Beckn fabric To participate in a Beckn network, you must publish your subscriber details on DeDi Global so that other participants can discover your endpoint and verify your signatures. Your verified namespace and registry act as your root of trust on the Beckn fabric. #### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#what-you-are-publishing) What you are publishing By registering your subscriber details, you make the following information available in a standard form: * your subscriber identity * your Beckn callback URL * your role on the network, such as BAP or BPP * your signing public key * any other subscriber metadata required by the schema Once these details are published, the NFO can reference your registry or record in its own network registry to include you in a specific Beckn network. #### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#step-1-set-up-your-dedi-account) Step 1 - Set up your DeDi account Create an account on [DeDi Global](https://dedi.global/). #### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#step-2-create-and-verify-your-namespace) Step 2 - Create & verify your namespace 1. Create a namespace. 2. Request for whitelisting of a domain. This can be done [here](https://docs.google.com/forms/d/e/1FAIpQLScAwEZh94DCIw70zrxWUJ1cud_wYfo_WEjqDpEmbxaw5ZF9aw/viewform) . The request will be processed within 5 minutes, provided no adverse signals are detected for the domain. 3. Enter the domain name. A TXT record will be generated (only for whitelisted domains). 4. Copy the generated TXT record as it needs to be updated in the DNS configuration file of your domain. 5. Click β€œVerify” after you have successfully updated the domain’s DNS file. The DNS text propagation will take from 15 min to up to 48 hours. Once this is done, your domain is verified. After you claim your organization's namespace by proving domain ownership, this namespace becomes your root of trust. Example: If you as an NP operate example-np.com, your namespace will be anchored to that domain. #### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#step-3-add-a-registry-under-your-namespace) Step 3 - Add a registry under your namespace Under your verified namespace, create a registry using the Beckn subscriber schema. This registry will contain one or more subscriber records for your organization. #### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#step-4-publish-your-subscriber-record) Step 4 - Publish your subscriber record Create a subscriber record with the following details: **Field** **What to fill** **Example** Subscriber ID Your unique identifier, typically your domain np.example.com Subscriber URL Your Beckn ONIX receiver endpoint https://np.example.com/bap/beckn Type Your role on the network BAP or BPP Domain Deprecated field; can be ignored \* Signing Public Key Your Ed25519 public key, Base64-encoded, without header or footer eyAeqGFtAuks... Encryption Public Key Optional encryption public key lCI84I0Q0U0w... Countries Countries where you operate \["IND"\] If you operate in multiple roles, publish separate records for each role. **Generating the signing keypair to be used in ONIX** You can use [this](https://github.com/beckn/beckn-onix/blob/main/install/generate-ed25519-keys.go) utility script provided in ONIX to generate your keypair. You can use any other utility as well as long as it is an Ed25519 key pair and you provide the private key as the raw 32-byte Ed25519 seed and the public key as the raw 32-byte Ed25519 public key, both Base64-encoded using standard RFC 4648 Base64 with padding. Once you click on publish the record will be published. Once published please make a note of the record ID. This will essentially be your key ID which you will configure in ONIX. #### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#step-5-verify-your-key-lookup) Step 5 - Verify your key lookup Use the following URL to check if your key has been cached successfully by the service: Please allow 5-10 minutes for the cache to be updated. #### [](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#why-this-matters) Why this matters Other participants use your published subscriber details to: * resolve your endpoint during transactions * retrieve your public key during signature verification * validate that the requests you send are authentic and untampered After publishing these details, your next step is to configure and deploy ONIX so it uses the same subscriber identity, key ID, and private key that correspond to the published record. [PreviousSetting up the network environment](https://docs.nfh.global/beckn/creating-an-open-network/setting-up-the-network-environment) [NextConfiguring Network Policies](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies) Last updated 1 month ago Was this helpful? * [Adding or onboarding Network Participants](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#adding-or-onboarding-network-participants) * [Network Participants registering on the fabric](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#network-participants-registering-on-the-fabric) * [4.1 Registering your subscription details on Beckn fabric](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#id-4.1-registering-your-subscription-details-on-beckn-fabric) Was this helpful? GitBook AssistantAskCopy
GitBook AssistantAskCopy https://fabric.nfh.global/registry/dedi/lookup//subscribers.beckn.one/ --- # Connect to everything using Beckn ONIX | Beckn Networks | NFH Fabric ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#overview) Overview Beckn-ONIX is an enterprise-grade middleware adapter system designed to facilitate seamless communication in any Beckn-enabled network. It acts as a protocol adapter between Beckn Application Platforms (BAPs - buyer applications) and Beckn Provider Platforms (BPPs - seller platforms), ensuring secure, validated, and compliant message exchange across various commerce networks. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#features) Features #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#plugin-based-architecture) πŸ”Œ **Plugin-Based Architecture** * **Dynamic Plugin Loading**: Load and configure plugins at runtime without code changes * **Extensible Design**: Easy to add new functionality through custom plugins * **Hot-Swappable Components**: Update plugins without application restart (in development) #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#enterprise-security) πŸ” **Enterprise Security** * **Ed25519 Digital Signatures**: Cryptographically secure message signing and validation * **Vault Integration**: Centralized secrets and key management * **Request Authentication**: Every message is authenticated and validated * **TLS/SSL Support**: Encrypted communication channels #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#protocol-compliance) βœ… **Protocol Compliance** * **JSON Schema Validation**: Ensures all messages comply with Beckn protocol specifications * **Version Management**: Support for multiple protocol versions simultaneously * **Domain-Specific Schemas**: Tailored validation for different business domains #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#high-performance) πŸš€ **High Performance** * **Caching**: Response caching for improved performance * **Queue Integration**: Asynchronous message processing via message queues * **Connection Pooling**: Efficient resource utilization * **Configurable Timeouts**: Fine-tuned performance controls #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#observability) πŸ“Š **Observability** * **Structured Logging**: JSON-formatted logs with contextual information * **Transaction Tracking**: End-to-end request tracing with unique IDs * **Metrics Support**: Performance and business metrics collection * **Health Checks**: Liveness and readiness probes for Kubernetes #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#usecase-domain-agnostic) 🌐 **Usecase/Domain Agnostic** * **Retail & E-commerce**: Product search, order management, fulfillment tracking * **Mobility Services**: Ride-hailing, public transport, vehicle rentals * **Logistics**: Shipping, last-mile delivery, returns management * **Healthcare**: Appointments, telemedicine, pharmacy services * **Financial Services**: Loans, insurance, payments For more detailed information, developer guides please visit Beckn ONIX [repository](https://github.com/Beckn-One/beckn-onix) [PreviousProve anything using VC on Edge](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/prove-anything-using-vc-on-edge) [NextGetting started with Beckn](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn) Last updated 1 month ago Was this helpful? * [Overview](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#overview) * [Features](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix#features) Was this helpful? --- # Configuring Network Policies | Beckn Networks | NFH Fabric Once the network environment exists, the network facilitator can define rules that apply across that network. In Beckn, these rules are configured at the network level through a manifest published by the Network Facilitator Organization (NFO) for a specific `network_id`. This allows all participants on that network to discover the same policy configuration and apply it consistently. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#what-network-policy-configuration-does) What network policy configuration does Network policy configuration gives the NFO a standard way to publish: * which policy artifacts apply to the network * where those policy artifacts are hosted * how participants should evaluate them In practice, this means the network can enforce shared business and validation rules without each participant implementing a separate, custom integration. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#the-role-of-the-manifest) The role of the manifest The manifest is the network-level configuration document associated with a specific registry and `network_id`. It is typically published as a signed YAML file and linked from the metadata of the NFO's network registry. Participants use the manifest to discover: * the policy source type * the artifact URL * the evaluation query path * the signing key information required for verification * the governance validity window for that release ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#registry-metadata-required-for-policy-discovery) Registry metadata required for policy discovery The NFO registry should expose metadata that points to the manifest and its signature material. The key fields are: * `manifest_url` * `manifest_signature_url` * `signing_public_key_lookup_url` This allows participants and Beckn ONIX instances to fetch the manifest and verify that it was published by the expected network authority. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#policy-configuration-in-the-manifest) Policy configuration in the manifest The manifest defines policy configuration inside the `policies` section. At a high level: * `type` identifies the policy language * `source` identifies how the policy is distributed * either a `bundle` section or a `file` section describes the final published artifact #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#example-using-an-opa-bundle) Example using an OPA bundle #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#example-using-a-single-rego-file) Example using a single Rego file ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#supported-policy-distribution-models) Supported policy distribution models At present, network policies can be distributed in two ways: * as an **OPA bundle** * as a single **Rego file** Exactly one of these should be used for a given policy reference in the manifest. The `policy_query_path` identifies the decision rule that participants should evaluate from that policy artifact. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#recommended-configuration-flow) Recommended configuration flow Use the following sequence when configuring policies for a network: 1. Decide which rules should be enforced at the network level. 2. Prepare the final published policy artifact for those rules. 3. Publish the artifact at a stable URL. 4. Add the `policies` section to the manifest for the target `network_id`. 5. Sign and publish the manifest. 6. Update the NFO registry metadata so participants can discover the latest manifest. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#detailed-guides) Detailed guides Use the following pages for the detailed operational steps: * 3.3.1 [Creating and publishing the network manifest](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest) * 3.3.2 [Creating and publishing Rego policy artifacts](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts) [PreviousOnboarding Network Participants](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants) [NextCreating and publishing the network manifest](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest) Last updated 1 month ago Was this helpful? * [What network policy configuration does](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#what-network-policy-configuration-does) * [The role of the manifest](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#the-role-of-the-manifest) * [Registry metadata required for policy discovery](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#registry-metadata-required-for-policy-discovery) * [Policy configuration in the manifest](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#policy-configuration-in-the-manifest) * [Supported policy distribution models](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#supported-policy-distribution-models) * [Recommended configuration flow](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#recommended-configuration-flow) * [Detailed guides](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies#detailed-guides) Was this helpful? GitBook AssistantAskCopy policies: type: "rego" source: "bundle" bundle: id: "network-policy-bundle" url: "https://example.org/policies/bundle.tar.gz" policy_query_path: "data.retail.policy.result" signing_public_key_id: "key-reg/prod-policy-key" GitBook AssistantAskCopy policies: type: "rego" source: "file" file: id: "network-policy-file" url: "https://example.org/policies/network.rego" policy_query_path: "data.retail.policy.result" signed: true signature_url: "https://example.org/policies/network.rego.sig" signing_public_key_id: "key-reg/prod-policy-key" --- # Useful links | Beckn Networks | NFH Fabric Resource Description [Beckn Protocol v2](https://github.com/beckn/protocol-specifications-v2) v2.0 spec with JSON-LD/schema.org-aligned core schema, modular schema packs, and CDS-based discovery for decentralized commerce networks. [Beckn Schema Registry](https://schema.beckn.io/) Collaborative registry of 345+ schema types and definitions for Beckn Protocol across mobility, logistics, energy, and financial services. [Beckn-ONIX](https://github.com/beckn/beckn-onix) Plugin-based middleware adapter enabling secure, validated message exchange between BAPs and BPPs across Beckn networks. [DeDi Docs](https://dedi-global.gitbook.io/docs) Universal decentralized directory infrastructure for public registries β€” public keys, membership, and revocation β€” under Linux Foundation Decentralized Trust. [OpenCred](https://opencred.global/) Open infrastructure for issuing tamper-proof, W3C-compliant verifiable credentials with zero data storage, by Networks for Humanity. [DEG](https://github.com/beckn/DEG) Specs for an interoperable digital energy ecosystem enabling decentralized energy contracts for production, consumption, and storage. [PreviousSigning a single file](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file) Last updated 1 month ago Was this helpful? Was this helpful? --- # Developer documentation | DeDi | NFH Fabric Everything you need to integrate with DeDi.global β€” from first API call to production deployment. #### [](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation#dedi-101) πŸ“˜ DeDi 101 Understand the three-tier architecture (Namespace β†’ Registry β†’ Record) and core protocol concepts. [Read DeDi 101 β†’](https://docs.nfh.global/dedi/dedi.global-developers/dedi-101) #### [](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation#quickstart) πŸš€ Quickstart Set up your account, create a namespace, verify your domain, and publish your first registry. [Get started β†’](https://docs.nfh.global/dedi/dedi.global-developers/quickstart) #### [](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation#api-reference) πŸ“‘ API Reference Complete documentation for all DeDi.global APIs β€” Publish, Access, Domain Verification, Delegation, State Management, Search, Subscriptions, and Verification. [View API Reference β†’](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis) #### [](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation#guides) πŸ“– Guides Practical how-tos for schema design, bulk upload, delegation, state management, and the Watch feature. [Browse Guides β†’](https://docs.nfh.global/dedi/dedi.global-developers/guides) #### [](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation#api-tools-and-resources) πŸ”§ API Tools & Resources Postman Collection and OpenAPI Specification for testing, code generation, and integration. View Tools β†’ [PreviousHow are DeDi.global entries cryptographically secured?](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured) [NextDeDi 101](https://docs.nfh.global/dedi/dedi.global-developers/dedi-101) Last updated 1 month ago Was this helpful? Was this helpful? --- # Use DeDi in your workflows | DeDi | NFH Fabric DeDi’s information architecture is organized around three key constructs: * **Namespace:** Corresponds to an organization (and implicitly to a domain name) as a starting point for trust. * **Directory:** Refers to a list of records with configurable schemas. * **Records:** The actual values or pointers to information. **Get started in 5 min with dedi.global:** 1 **Create your account** Register yourself on [dedi.global](https://dedi.global/) using relevant email 2 **Claim your namespace** Create a namespace and verify it against your domain 3 **Publish your registries** Publish your first directory using any schema 4 **Look up and query info using DeDi** Adopt the DeDi Protocol to start looking up and querying public records in verification flows. globe-pointer More detailed information on getting started can be found [here](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation) . [PreviousWelcome to DeDi.global](https://docs.nfh.global/dedi) [NextThe vision for Decentralised Directory (DeDi)](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi) Last updated 1 month ago Was this helpful? Was this helpful? --- # Signing a single file | Beckn Networks | NFH Fabric OpenSSL can create digital signatures using a private key and verify them using the corresponding public key. These same steps can be used to sign the network manifest file as well as any single file artifacts referenced in the manifest. The recommended algorithm is `ES256` using an ECDSA P-256 keypair. `EdDSA` is a modern alternative, but `ES256` is preferred here because it has better support in OPA's runtime verification path. [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-1.-prerequisites) 1\. Prerequisites -------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#openssl-version) OpenSSL Version These commands require OpenSSL, not LibreSSL. LibreSSL sometimes lacks support for certain signing commands or behaves differently from OpenSSL, so it is recommended to use openssl if you are following this guide. Check your version: GitBook AssistantAskCopy openssl version Expected output should look similar to: GitBook AssistantAskCopy OpenSSL 1.1.1x or GitBook AssistantAskCopy OpenSSL 3.x.x Recommended versions: Version Status OpenSSL 3.x Recommended OpenSSL 1.1.1 Supported LibreSSL Not recommended If the output contains: install OpenSSL instead. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#required-files) Required Files You need: private.pem must contain the private key used for signing. And assume artifact.yaml is the file you need to sign which may be a network manifest or a policy rego file or any other artifact that needs to be signed by you. [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-2.-generate-a-key-pair-if-you-dont-already-have-one) 2\. Generate a Key Pair (If You Don’t Already Have One) --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you already have the key pair, you can skip this step. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#generate-a-private-key-ecdsa-p-256-for-es256) Generate a private key (ECDSA P-256 for ES256) ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#extract-the-public-key) Extract the public key Result: [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-3.-sign-the-file) 3\. Sign the File -------------------------------------------------------------------------------------------------------------------------------------------------------- Suppose you want to sign: artifact.yaml Run: Generated file: [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-4.-files-to-publish) 4\. Files to Publish -------------------------------------------------------------------------------------------------------------------------------------------------------------- When publishing the signed artifact, provide: If the signed file is an artifact referenced in the network manifest, the links of the published files should be added to the network manifest at the appropriate section based on the type of artifact that is being signed. If the signed file is the network manifest itself, it should be added as the manifest\_url in the metadata field of the NFO network registry this manifest is for. [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-5.-verifying-the-signature) 5\. Verifying the Signature ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Anyone with the public key can verify the file. Run: Expected output: If the file has been modified, verification will fail: [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-6.-security-best-practices) 6\. Security Best Practices ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- βœ” Keep private.pem secret βœ” Store private keys securely βœ” Never upload private keys βœ” Rotate keys periodically ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#recommended-naming-convention) Recommended Naming Convention Common pattern: Example: [PreviousCreating and publishing Rego policy artifacts](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts) [NextUseful links](https://docs.nfh.global/beckn/resources/useful-links) Last updated 1 month ago Was this helpful? * [1\. Prerequisites](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-1.-prerequisites) * [OpenSSL Version](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#openssl-version) * [Required Files](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#required-files) * [2\. Generate a Key Pair (If You Don’t Already Have One)](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-2.-generate-a-key-pair-if-you-dont-already-have-one) * [Generate a private key (ECDSA P-256 for ES256)](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#generate-a-private-key-ecdsa-p-256-for-es256) * [Extract the public key](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#extract-the-public-key) * [3\. Sign the File](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-3.-sign-the-file) * [4\. Files to Publish](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-4.-files-to-publish) * [5\. Verifying the Signature](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-5.-verifying-the-signature) * [6\. Security Best Practices](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#id-6.-security-best-practices) * [Recommended Naming Convention](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file#recommended-naming-convention) Was this helpful? GitBook AssistantAskCopy LibreSSL GitBook AssistantAskCopy private.pem artifact.yaml GitBook AssistantAskCopy openssl ecparam -name prime256v1 -genkey -noout -out private.pem GitBook AssistantAskCopy openssl pkey -in private.pem -pubout -out public.pem GitBook AssistantAskCopy private.pem public.pem GitBook AssistantAskCopy openssl dgst -sha256 -sign private.pem -out artifact.yaml.sig artifact.yaml GitBook AssistantAskCopy artifact.yaml.sig GitBook AssistantAskCopy artifact.yaml artifact.yaml.sig GitBook AssistantAskCopy openssl dgst -sha256 -verify public.pem -signature artifact.yaml.sig artifact.yaml GitBook AssistantAskCopy Verified OK GitBook AssistantAskCopy Verification Failure GitBook AssistantAskCopy file.ext file.ext.sig GitBook AssistantAskCopy artifact.yaml artifact.yaml.sig --- # FAQs | DeDi | NFH Fabric #### [](https://docs.nfh.global/dedi/miscellaneous/faqs#general) General **Q: What is DeDi?** DeDi (Decentralized Directory) is an open protocol under Linux Foundation Decentralized Trust that defines a universal way to publish, discover, and verify public information. DeDi.global is a hosted implementation of this protocol, operated by Networks for Humanity Foundation. **Q: Is DeDi free?** Yes. DeDi.global is free to publish on and free to query. There are no licensing fees, contracts, or exit clauses. **Q: Is my data public?** Yes β€” DeDi is designed for public registries. Lookup and Query APIs are publicly accessible without authentication. If your data is sensitive or private, DeDi is not the right tool. **Q: How is DeDi different from a blockchain?** DeDi is not a blockchain. It is a directory protocol with a RESTful API. However, every entry's cryptographic proof is anchored on the CORD blockchain to provide tamper-evidence and auditability. You interact with DeDi via standard HTTPS APIs, not blockchain transactions. **Q: Can I run my own DeDi node?** DeDi is built on the open Decentralized Directory Protocol (DDP). Anyone can implement the protocol independently. DeDi.global is one implementation β€” not the only one. * * * #### [](https://docs.nfh.global/dedi/miscellaneous/faqs#account-and-setup) Account & Setup **Q: How do I create an account?** Register at [publish.dedi.global](https://publish.dedi.global/) with your email and a password (6+ characters with at least one special character). You'll receive a magic link to verify your email. **Q: How do I get an API key?** After registration and email verification, log in and use the "Get API Key" option in your profile, or call `GET /dedi/get-api-key` while authenticated. Include the key as a Bearer token in all API requests. * * * #### [](https://docs.nfh.global/dedi/miscellaneous/faqs#domain-verification) Domain Verification **Q: Is domain verification mandatory?** No, but it is strongly recommended. Verification links your namespace to your domain, making API paths human-readable (e.g., `/dedi/your-domain.com/registry/record` instead of a hash) and establishing organizational provenance. **Q: How long does domain verification take?** The domain whitelisting request is typically processed within ~5 minutes. After adding the DNS TXT record, DNS propagation can take up to 24–48 hours depending on your DNS provider. **Q: Can I use DeDi without domain verification?** Yes. You can create namespaces, registries, and records without verification. Your namespace will use a system-generated ID instead of your domain name. * * * #### [](https://docs.nfh.global/dedi/miscellaneous/faqs#data-and-schemas) Data & Schemas **Q: What credential formats does DeDi support?** DeDi is format-agnostic. It supports the co-existence of multiple data standards and schemas, including VC JSON-LD, mDocs/mDL, and custom JSON Schema (Draft 7). You define the schema when creating a registry. **Q: Can I define custom schemas?** Yes. You can provide any valid JSON Schema (Draft 7) when creating a registry. DeDi also offers pre-built schema templates (Membership, Public Key, Revocation, Beckn One). **Q: Can I bulk upload data via API?** Yes. DeDi provides a `POST /dedi/bulk-upload` endpoint that accepts CSV files via multipart/form-data. You can also bulk upload through the UI. See the [Bulk Upload guide](https://claude.ai/dedi.global-developers/guides/bulk-upload) for details. **Q: What happens if schemas don't match during upload?** The upload will fail. Schema consistency is required β€” your CSV column headers must match the registry's schema property names, and values must conform to the defined types. * * * #### [](https://docs.nfh.global/dedi/miscellaneous/faqs#verification-and-trust) Verification & Trust **Q: How do I verify that a DeDi entry hasn't been tampered with?** Every DeDi entry includes a cryptographic proof (BLAKE2 H256 digest) anchored on the CORD blockchain. You can verify by recalculating the digest from the entry's fields and comparing it to the proof. You can also verify directly on-chain via [apps.cord.network](https://apps.cord.network/) . **Q: Can I subscribe to changes in a registry?** Yes. The Watch feature lets you subscribe to changes on namespaces, registries, specific records, or schema tags. You receive notifications when entries are created, updated, or their state changes. * * * #### [](https://docs.nfh.global/dedi/miscellaneous/faqs#migration-and-portability) Migration & Portability **Q: How do I migrate from another registry to DeDi?** Export your existing data as CSV, map your columns to a DeDi schema, and use the bulk upload feature. If you have a custom data format, define a matching JSON Schema when creating your registry. **Q: Can I export my data from DeDi?** Yes. Your data is exportable as standard JSON β€” fully portable. * * * #### [](https://docs.nfh.global/dedi/miscellaneous/faqs#support) Support For additional questions, [contact support](https://docs.google.com/forms/d/e/1FAIpQLSesBZMkgmnKY3SDzGQPDF8E-OoAo75O5n4LVrdoDKFtz_Y3FA/viewform) . [PreviousOpenAPI Specification](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification) [NextGlossary](https://docs.nfh.global/dedi/miscellaneous/glossary) Last updated 1 month ago Was this helpful? Was this helpful? --- # Build Trusted Networks using REGISTR | Beckn Networks | NFH Fabric [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#executive-summary) **Executive Summary** ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Digital ecosystems across sectorsβ€”commerce, mobility, energy, sustainability, public services, and moreβ€”need a reliable way for participants to identify, authenticate, and communicate with each other. Today, this often requires custom integrations, manual key exchanges, or sector-specific directories that don’t scale. The **Beckn Registry Service**, built on the [DeDi Global](https://dedi.global/) infrastructure, an implementation of the [Decentralized Directory Protocol (DeDi)](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol) , provides a verifiable identity directory for any Beckn-enabled participant. It enables organizations of all types to publish network identity under their own domains, ensuring **trusted addressability** and interoperability across Beckn-based networks. [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-1.-why-the-registry-service-matters) **1\. Why the Registry Service Matters** -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#the-problem-today) **The Problem Today** Many facilitators and network operators maintain their own directories of participants. As networks expand, keeping these directories in sync, verifying identities, and updating configuration data becomes increasingly complex. Because each directory is independently operated, they naturally become isolated, making cross-network interaction more difficult. The Beckn Registry Service provides a shared, protocol-aligned foundation for publishing identity information while allowing facilitators to continue curating and governing their networks as they always have. [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-2.-the-beckn-approach) **2\. The Beckn Approach** ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Registry Service provides: #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#global-addressability) **βœ“ Global Addressability** Every Beckn-compatible participant gets a resolvable, protocol-standard identity under a verified namespaceβ€”making it straightforward for entities to reference, validate, and interact with one another. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#self-owned-identity-records) **βœ“ Self-Owned Identity Records** Participants publish their own subscriber information under their own domain, ensuring autonomy and reducing duplication across registries. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#cryptographic-trust-without-manual-effort) **βœ“ Cryptographic Trust Without Manual Effort** Public keys, domain proofs, and signing details are published in a consistent, verifiable format. This removes the need for custom key exchanges or facilitator-specific trust setups. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#seamless-integration-with-beckn-onix) **βœ“ Seamless Integration with Beckn ONIX** [Beckn ONIX](https://github.com/beckn/beckn-onix) automatically retrieves subscriber details during transactions. No additional registry APIs, integrations, or onboarding workflows are needed. The result is a simpler, more coherent technical foundation that empowers facilitators while strengthening the entire network. [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-3.-what-the-registry-service-enables) **3\. What the Registry Service Enables** ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#a.-global-addressability) **a. Global Addressability** A uniform, protocol-defined way to reference participants across ecosystemsβ€”regardless of sector or facilitator. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#b.-verifiable-trust-layer) **b. Verifiable Trust Layer** Domain-anchored identities ensure: * Authenticity * Key validation * Signed request verification All without manual coordination. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#c.-structured-subscriber-data) **c. Structured Subscriber Data** Standardized schemas for: * Subscriber ID * Callback URLs * Domain codes * Network roles (BAP/BPP/CDS/etc.) * Public keys Ensuring compatible, predictable integrations. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#d.-facilitator-support) **d. Facilitator Support** Facilitators can publish **Subscription Reference Directories** β€” curated sets of participants β€” while relying on the registry service as the technical backbone for addressing and validation. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#e.-seamless-interoperability-with-beckn-onix) **e. Seamless Interoperability with Beckn ONIX** Beckn ONIX automatically: * Retrieves subscriber information * Fetches keys * Performs signing and verification Allowing participants to transact smoothly without extra integration steps. [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-4.-key-benefits) **4\. Key Benefits** ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#global-addressability-1) ⭐ **Global Addressability** A unified reference system for interacting with Beckn participants across domains and networks. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#secure-and-verifiable-interactions) πŸ”’ **Secure & Verifiable Interactions** Public keys and signing information are published in a consistent, verifiable manner. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#zero-integration-onboarding) ⚑ **Zero-Integration Onboarding** Participants simply publish their recordsβ€”no additional registry API implementation required. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#self-managed-identity) 🧩 **Self-Managed Identity** Participants maintain their own records with subscription data. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#applicable-across-sectors) ♻️ **Applicable Across Sectors** Suitable for commerce, mobility, health, energy, sustainability, public services, and any domain adopting Beckn. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#proven-to-scale) **πŸ“ˆ Proven to Scale** In the latest performance testing, the Registry Service handled datasets ranging from 100,000 to 1.5 million records while sustaining around 1,000 requests per second on modest infrastructure. In larger configurations, it scaled to over 2,200 requests per second with p95 latency of about 42 ms, demonstrating strong performance for high-volume, low-latency network workloads. [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-5.-who-should-use-this-service) **5\. Who Should Use This Service** ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#organizations-building-beckn-enabled-systems) **Organizations Building Beckn-Enabled Systems** Across any sector β€” energy, mobility, sustainability, commerce, public services, etc. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#developers) **Developers** Implement Beckn flows without managing discovery, key-exchange setups, or custom integrations. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#facilitators-and-network-operators) **Facilitators & Network Operators** Curate and govern networks with ease, without carrying the full technical maintenance burden of identity/addressability infrastructure. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#enterprises-and-agencies) **Enterprises & Agencies** Standardize trust and identity across wide-ranging digital ecosystems. [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-6.-how-it-works) **6\. How It Works** ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. **Namespace Creation** Create and verify domain ownership to establish an identity namespace. 2. **Registry Publication** Add a registry to list beckn subscriber details. 3. **Subscriber Record Creation** Publish callback URL, roles, domain codes, and public keys. 4. **Beckn ONIX Interaction** Beckn ONIX automatically resolves subscriber details during network interactions. [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-7.-typical-user-journey) **7\. Typical User Journey** -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#create-and-verify-namespace) **Create & Verify Namespace** Prove domain ownership and establish your identity namespace. 2 ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#add-a-registry) **Add a Registry** Publish a registry following the Beckn subscriber schema. 3 ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#add-subscriber-records) **Add Subscriber Records** Include your callback URLs, roles, domain codes, and keys. 4 ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#transact-through-beckn-onix) **Transact through Beckn ONIX** Start participating in Beckn interactions with automatic address resolution and trust validation. [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-8.-glossary) **8\. Glossary** -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **Namespace**: A verified identity space tied to an organization’s domain and used as the root of trust for publishing participant information.. * **Registry**: A list of subscriber records under your namespace. * **Subscriber Record**: The specific values describing how a participant can be addressed and authenticatedβ€”such as URLs, roles, domain codes, and public keys. * **Facilitator**: An entity that curates and governs networks using Beckn standards. * **Domain Code**: Represents a domain like mobility, commerce, energy, or sustainability. * [**Beckn ONIX**](https://github.com/Beckn-One/beckn-onix) : An enterprise-grade middleware adapter that enables seamless communication in Beckn-enabled networks by handling routing, key retrieval, and validation. * **DeDi Global**: Infrastructure implementing the Decentralized Directory Protocol. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-9.-get-started) **9\. Get Started** -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#user-guide) **πŸ“˜ User Guide** * If you are a **Network Facilitator Organization (NFO)** and want to set up a new Beckn network, create a registry, and onboard participants β€” [Setting up the network environment](https://docs.nfh.global/beckn/creating-an-open-network/setting-up-the-network-environment) * If you are a **Network Participant (NP)** and want to register your subscriber details on the fabric β€” [Registering on the fabric](https://docs.nfh.global/beckn/creating-an-open-network/onboarding-network-participants#network-participants-registering-on-the-fabric) ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#need-help) **πŸ’¬ Need Help?** Raise a support ticket [here](https://forms.gle/6sQqZeEnMYyBPc4f7) . [PreviousPublish API Performance Benchmarking](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api) [NextRegistry Service Performance Benchmarking](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark) Last updated 7 days ago Was this helpful? * [Executive Summary](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#executive-summary) * [1\. Why the Registry Service Matters](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-1.-why-the-registry-service-matters) * [The Problem Today](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#the-problem-today) * [2\. The Beckn Approach](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-2.-the-beckn-approach) * [3\. What the Registry Service Enables](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-3.-what-the-registry-service-enables) * [4\. Key Benefits](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-4.-key-benefits) * [5\. Who Should Use This Service](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-5.-who-should-use-this-service) * [6\. How It Works](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-6.-how-it-works) * [7\. Typical User Journey](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-7.-typical-user-journey) * [Create & Verify Namespace](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#create-and-verify-namespace) * [Add a Registry](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#add-a-registry) * [Add Subscriber Records](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#add-subscriber-records) * [Transact through Beckn ONIX](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#transact-through-beckn-onix) * [8\. Glossary](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-8.-glossary) * [9\. Get Started](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#id-9.-get-started) * [πŸ“˜ User Guide](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#user-guide) * [πŸ’¬ Need Help?](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr#need-help) Was this helpful? --- # Setup for using DeDi APIs | DeDi | NFH Fabric DeDi Global provides one environment: * **Production Environment** β†’ `publish.dedi.global` **Steps** 1. Register on the platform as detailed [here](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation) . 2. Generate an **API token**. 3. Use the appropriate server: * Production: `api.dedi.global` [PreviousUser Guide - DeDi.Global namespace & directory creation](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation) [NextDomain Verification - The bedrock of trust in DeDi](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi) Last updated 1 month ago Was this helpful? Was this helpful? --- # Appendix: Three types of verification | DeDi | NFH Fabric In the digital world, establishing trust in any piece of information, whether it's a document, a transaction, or a digital credential, relies on three fundamental pillars: **Integrity, Validity, and Authenticity.** 1. **Integrity:** 1. **What it means:** Integrity means no changes. The data matches the original exactly. Integrity check means to verify if the information has not been changed, altered, or tampered with since it was originally created or issued. It's about making sure the data is exactly as the sender intended it to be, without any unauthorized modifications. 2. **How it's checked:** This is often verified using digital signatures or cryptographic hash functions. A unique "fingerprint" of the data is created when it's issued. If even a single character is changed, the fingerprint will no longer match, indicating tampering. 3. **Example**: Imagine a digital degree certificate. If someone tries to change your grade from a 'B' to an 'A' after it's been issued, the integrity check would fail because the digital signature on the certificate would no longer be valid for the altered content. 2. **Validity:** 1. **What it means:** Validity means still current. The information hasn't expired or been canceled. Validity check means to verify if the information is still current, relevant, and has not been revoked, expired, or superseded. It addresses whether the information is still "good" to use at the present time. 2. **How it's checked:** This typically involves checking against revocation lists (lists of certificates or credentials that have been cancelled), expiration dates, or updated versions of the information. 3. **Example:** A digital driver's license has an expiration date. Even if it's authentic and hasn't been tampered with, it becomes invalid after that date. Similarly, a digital certificate issued to a company might be revoked if the company goes out of business or its security is compromised. 3. **Authenticity:** 1. **What it means:** Authenticity means real source. The information comes from who it claims to come from. Authenticity check means to verify if the source of the information is genuinely who or what it claims to be. It's about trusting the origin of the data. 2. **How it's checked:** This is established by verifying the digital signature against the issuer's publicly listed digital certificate, public key, or other trusted identifiers. It also involves checking if the issuer is a recognized and authorized entity (e.g., a university accredited to issue degrees, a bank licensed to operate). 3. **Example:** If you receive a digital invoice, authenticity ensures that it truly came from the company you did business with, not a fraudster pretending to be them. You would check the company's digital signature and verify that the signing certificate was issued by a trusted Certificate Authority and that the company is a legitimate, registered business. [PreviousThe vision for Decentralised Directory (DeDi)](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi) [NextHow to Use DeDi](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi) Last updated 1 month ago Was this helpful? Was this helpful? --- # DeDi in Verifiable Credential Workflows | DeDi | NFH Fabric [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#dedi-in-verifiable-credential-workflows) DeDi in Verifiable Credential Workflows ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- DeDi serves as a **directory and trust layer** for verifiable credential (VC) ecosystems β€” complementing DIDs and DID Documents by providing discoverable, auditable registries of issuers, keys, schemas, and credential status. > For specific registry implementations, see [Representative Use Cases](https://claude.ai/resources/representative-use-cases) > . ### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#the-verifiers-problem) The Verifier's Problem When a verifier receives a credential, they need answers to five questions: 1. Is this DID valid and current? 2. Which public key should verify the signature? 3. Was this key valid when the credential was issued? 4. Has this credential been revoked? 5. Is this issuer trusted in my trust network? DID Documents answer questions 1–2 for a single identifier. **DeDi addresses all five across entire ecosystems.** ### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#what-dedi-provides) What DeDi Provides #### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#id-1.-unified-key-discovery) 1\. Unified Key Discovery Public keys are scattered across email headers, key servers, DNS records, and proprietary directories. DeDi lets organizations publish keys to a claimed namespace. Verifiers query one standardized API regardless of the underlying DID method. #### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#id-2.-auditable-key-history) 2\. Auditable Key History DID Documents show current state only. In DeDi, every key change is a versioned record with cryptographic provenance anchored on-chain. Verifiers can retrieve the key that was valid at any point in time, and subscribe to alerts when keys change. #### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#id-3.-revocation-and-status-lists) 3\. Revocation and Status Lists Issuers publish status lists (revoked credentials, suspended issuers) as standardized, machine-readable registries on DeDi. Updates propagate immediately and are tamper-evident via on-chain anchoring. #### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#id-4.-trusted-issuer-directories) 4\. Trusted Issuer Directories Authoritative bodies (regulators, accreditors, industry associations) publish directories of recognized issuers. Verifiers configure which namespaces they trust, then automatically accept issuers listed under those namespaces. #### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#id-5.-vc-schema-registry) 5\. VC Schema Registry Issuers publish VC schemas as registry records with full version history and provenance tracking. Verifiers retrieve the exact schema version referenced by a credential. ### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#how-it-works) How It Works **Issuer Setup:** 1. Register a namespace on DeDi 2. Publish registries for public keys, VC schemas, and status lists 3. Each publish operation is signed and anchored on-chain **Credential Issuance:** The issuer signs the VC with their current key. The VC contains the issuer DID and optionally references DeDi for schema and status list. **Verification Flow:** DeDi complements DID Documents: **DID Document** = cryptographic material for one identity; **DeDi** = discovery, trust context, and status across many identities. ### [](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#summary) Summary DeDi doesn't replace DIDs β€” it makes them **usable at scale** by answering the questions that DID Documents alone cannot. All answers are machine-readable, API-accessible, and cryptographically anchored. [PreviousVC Signing Keys on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi) [NextHow are DeDi.global entries cryptographically secured?](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured) Last updated 1 month ago Was this helpful? * [DeDi in Verifiable Credential Workflows](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#dedi-in-verifiable-credential-workflows) * [The Verifier's Problem](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#the-verifiers-problem) * [What DeDi Provides](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#what-dedi-provides) * [How It Works](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#how-it-works) * [Summary](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows#summary) Was this helpful? GitBook AssistantAskCopy Verifier receives VC with issuer DID ↓ Query DeDi: β€’ Is issuer in a trusted namespace? β€’ What key was valid at issuance time? β€’ Is credential on any status list? β€’ What schema version applies? ↓ Resolve DID Document, cross-check key with DeDi ↓ Verify signature β†’ Accept or Reject --- # Quickstart | DeDi | NFH Fabric Go from zero to your first published registry [User Guide - DeDi.Global namespace & directory creation](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation) [Setup for using DeDi APIs](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/setup) [Domain Verification - The bedrock of trust in DeDi](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi) [PreviousDeDi 101](https://docs.nfh.global/dedi/dedi.global-developers/dedi-101) [NextUser Guide - DeDi.Global namespace & directory creation](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation) Last updated 1 month ago Was this helpful? Was this helpful? --- # Postman Collection | DeDi | NFH Fabric The DeDi.global Postman collection provides a comprehensive set of pre-configured API requests for testing, development, and integration with the DeDi.global platform. [Download postman collection](https://github.com/nfh-trust-labs/docs/blob/main/postman-collection.json) ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#quick-setup) Quick Setup 1. **Import:** _Open Postman_ β†’ Click _Import_ β†’ _Paste the collection URL or upload the JSON file_ 2. **Configure Environment:** The collection includes variables for Base URL, API Key, and Namespace IDs 3. **Set Authentication:** In the collection's Authorization tab, select Bearer Token and enter your API key. All requests inherit this automatically. ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#collection-contents) Collection Contents 1. **Core Operations:** Authentication, Namespaces, Registries, Records (CRUD) 2. **Advanced Features:** Domain Verification, Bulk Operations (CSV import/export), Search & Query, Webhooks, Delegation & Access Control 3. **Administrative:** Lifecycle and recovery operations, Version Control ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#features) Features Pre-configured requests with proper headers, environment variables, test scripts, inline documentation, and error handling examples. ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#usage-tips) Usage Tips 1. Start with Authentication to get your API key 2. Use environment variables for base URLs and common IDs 3. Follow the workflow: Namespace β†’ Registry β†’ Record 4. Use automated response tests to catch issues ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#related-resources) Related Resources * [OpenAPI Specification](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification) : Complete API schema * [API Reference Documentation](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis) : Detailed endpoint documentation * [Quickstart Guide](https://docs.nfh.global/dedi/dedi.global-developers/quickstart) : Step-by-step integration guide ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#support) Support If you encounter issues with the Postman collection: 1. Check the [FAQ section](https://docs.nfh.global/dedi/miscellaneous/faqs) 2. Review the [API Reference](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis) for endpoint details 3. Contact support through our official channels [PreviousAPI Tools & Resources](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools) [NextOpenAPI Specification](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification) Last updated 1 month ago Was this helpful? * [Quick Setup](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#quick-setup) * [Collection Contents](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#collection-contents) * [Features](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#features) * [Usage Tips](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#usage-tips) * [Related Resources](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#related-resources) * [Support](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection#support) Was this helpful? --- # Creating and publishing the network manifest | Beckn Networks | NFH Fabric [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#guide-for-nfos-creating-and-publishing-network-manifest) Guide for NFOs - Creating & Publishing Network Manifest --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This guide explains how a Network Facilitator Organization (NFO) can create, publish, and maintain a network manifest for a Beckn network. The manifest is the control document for a given network\_id and allows the NFO to publish network-level configuration in a discoverable, versioned, and verifiable way. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-1.-overview) 1\. Overview In Beckn, the network\_id is tied to a specific registry maintained by the NFO. That registry represents the network boundary and acts as the network's root of trust. The network manifest is a signed YAML document associated with that registry and serves as the main release document for network-level configuration. Participants can use the manifest to discover: * which policies apply to the network * where those policy artifacts are hosted * whether observability is enabled * where telemetry configuration and collector endpoints are defined The manifest itself can be hosted by the NFO at any stable URL. The URL and signature metadata are then published as metadata on the NFO's network registry, allowing participants to resolve the current network configuration for that network\_id. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-2.-where-the-manifest-is-referenced) 2\. Where the manifest is referenced The NFO should attach manifest-related metadata to the network registry on DeDi Global. This allows participants and ONIX instances to discover the manifest for a specific network\_id. The registry metadata should contain: Field Description manifest\_url URL of the network manifest file manifest\_signature\_url URL of the detached signature for the manifest signing\_public\_key\_lookup\_url Lookup URL of the public key used to verify the manifest signature The signing public key referenced here should be retrievable through the registry lookup URL so that participants can verify the authenticity and integrity of the manifest. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-3.-relationship-between-registry-and-network-id) 3\. Relationship between registry and network ID The network\_id is formed from: For example: This means each network registry has its own manifest and its own network configuration. In practice, NFOs usually maintain separate registries and manifest for each environment boundary they are defining using their registries. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-4.-manifest-structure) 4\. Manifest structure The manifest is a YAML document for a specific network release. A typical manifest looks like this: ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-5.-top-level-fields) 5\. Top-level fields Field Required Description manifest\_version Yes Version of the manifest schema manifest\_type Yes Must be network-manifest network\_id Yes Network the manifest applies to release\_id Yes Release identifier for this manifest version publisher Yes Publisher identity information policies No Policy distribution and evaluation configuration observability No Telemetry and observability configuration governance Yes Validity period and signature state #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#publisher) Publisher Field Required Description role Yes Publisher role, typically NFO domain Yes Domain representing the publisher ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-6.-defining-policies-in-the-manifest) 6\. Defining policies in the manifest The manifest can point to network policies written in Rego. Policies may be distributed either as: * an OPA bundle * a single Rego file The policies section must declare the source format and the evaluation query path. #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#policy-section-rules) Policy section rules * type must currently be rego * source must be either bundle or file * exactly one of bundle or file must be present #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#example-using-an-opa-bundle) Example using an OPA bundle #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#example-using-a-single-rego-file) Example using a single Rego file The `policy_query_path` field should point to the decision rule that participants evaluate for that policy artifact. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-7.-creating-and-publishing-policy-artifacts) 7\. Creating and publishing policy artifacts Detailed guidance for policy authors, including the expected policy output contract, repository structure, build steps, signing flow, testing process, and publication of the final artifact, is covered in the separate guide: [Guide for NFOs: Creating and Publishing Rego Policy Artifacts](https://docs.google.com/document/d/1pk4bR-n_MLFTUF4ZY4MZvFwh1p0-3vB2RRw2EDLUsAg/edit?tab=t.ta9tsii5uhx8) . In the manifest, the NFO only needs to reference the final published artifact using the appropriate bundle or file section. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-8.-defining-observability-in-the-manifest) 8\. Defining observability in the manifest The manifest can also define network observability settings. This allows the NFO to standardize what telemetry participants emit and where that telemetry is sent as part of the network release. #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#observability-fields) Observability fields Field Required Description observability.enabled Yes Enables observability when true observability.config.url Conditional URL of the observability config document observability.config.signed Conditional Whether the config is signed observability.config.signature\_url Conditional Detached signature URL when signed observability.config.signing\_public\_key\_id Conditional Key identifier used for verification observability.collector.url Conditional Endpoint receiving telemetry events #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#example) Example The observability config document can describe required and optional telemetry fields or other network-wide telemetry rules. Participants should verify the configuration before using it. Please refer the [observability guide](https://github.com/beckn/beckn-onix/blob/main/pkg/plugin/implementation/otelsetup/OBSERVABILITY.md#audit-fields-configuration-configaudit-fieldsyaml) for the understanding the `config.url` parameter and how observability can be set up in Beckn ONIX. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-9.-governance-section) 9\. Governance section The governance section defines the validity window of the manifest. Example: #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#governance-rules) Governance rules * effective\_from defines when the manifest becomes active * if effective\_until is present, it must be later than effective\_from * once the current time passes effective\_until, the manifest should be treated as expired * if the manifest is signed, the detached signature and key lookup information must be available through registry metadata ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-10.-suggested-publishing-workflow) 10\. Suggested publishing workflow Use this sequence when publishing or updating a manifest: 1. Create or update policy artifacts. 2. Create or update observability configuration if required. 3. Publish all referenced files at stable URLs. 4. Create the manifest YAML for the target network\_id. 5. Sign the manifest. You can use [this guide](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file) to sign the manifest file. 6. Publish the manifest and detached signature. 7. Update the NFO registry metadata with manifest\_url, manifest\_signature\_url, and signing\_public\_key\_lookup\_url. 8. Roll out the new release and communicate the new release\_id to participants if needed. lightbulb Once published NPs can configure the same on thier beckn ONIX instances using the [policy checker](https://github.com/beckn/beckn-onix/tree/main/pkg/plugin/implementation/opapolicychecker) plugin. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-11.-operational-recommendations) 11\. Operational recommendations * version releases clearly using release\_id * keep artifact URLs stable and preferably immutable * test policies before publishing them into production manifests * avoid mixing unrelated policy changes and observability changes in one release unless necessary * ensure registry metadata always points to the currently intended manifest for that network The manifest is the NFO's main distribution mechanism for network-level configuration. Treat it as a versioned, signed contract between the NFO and all participants operating on that network\_id. [PreviousConfiguring Network Policies](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies) [NextCreating and publishing Rego policy artifacts](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts) Last updated 1 month ago Was this helpful? * [Guide for NFOs - Creating & Publishing Network Manifest](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#guide-for-nfos-creating-and-publishing-network-manifest) * [1\. Overview](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-1.-overview) * [2\. Where the manifest is referenced](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-2.-where-the-manifest-is-referenced) * [3\. Relationship between registry and network ID](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-3.-relationship-between-registry-and-network-id) * [4\. Manifest structure](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-4.-manifest-structure) * [5\. Top-level fields](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-5.-top-level-fields) * [6\. Defining policies in the manifest](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-6.-defining-policies-in-the-manifest) * [7\. Creating and publishing policy artifacts](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-7.-creating-and-publishing-policy-artifacts) * [8\. Defining observability in the manifest](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-8.-defining-observability-in-the-manifest) * [9\. Governance section](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-9.-governance-section) * [10\. Suggested publishing workflow](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-10.-suggested-publishing-workflow) * [11\. Operational recommendations](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest#id-11.-operational-recommendations) Was this helpful? GitBook AssistantAskCopy / GitBook AssistantAskCopy example-nfo.com/production GitBook AssistantAskCopy manifest_version: "1.0" manifest_type: "network-manifest" network_id: "nfo.com/production" release_id: 2026.02 publisher: role: "NFO" domain: "nfo.example.org" policies: type: "rego" source: "bundle" bundle: id: "network-policy-bundle-v0.1" url: "https://nfo.example.org/policies/network-policy-bundle-0.1.tar.gz" policy_query_path: "data.retail.validation.result" signing_public_key_url: "ac0bc933-3862-481d-ac8b-d87642a5e994" observability: enabled: true config: url: "https://nfo.example.org/observ/fields.yaml" signed: true signature_url: "https://nfo.example.org/observ/fields.yaml.sig" signing_public_key_url: "ac0bc933-3862-481d-ac8b-d87642a5e994" collector: url: "https://telemetry.nfo.example.org/v1/network/events" governance: effective_from: "2026-03-10T00:00:00Z" effective_until: "2027-03-10T00:00:00Z" signed: true GitBook AssistantAskCopy policies: type: "rego" source: "bundle" bundle: id: "network-policy-bundle" url: "https://example.org/policies/bundle.tar.gz" policy_query_path: "data.retail.policy.result" signing_public_key_lookup_url: "key-reg/prod-policy-key" GitBook AssistantAskCopy policies: type: "rego" source: "file" file: id: "network-policy-file" url: "https://example.org/policies/network.rego" policy_query_path: "data.retail.policy.result" signed: true signature_url: "https://example.org/policies/network.rego.sig" signing_public_key_lookup_url: "https://fabric.nfh.global/dedi/lookup/nfo.org/key-reg/prod-policy-key" GitBook AssistantAskCopy observability: enabled: true config: url: "https://nfo.example.org/observ/fields.yaml" signed: true signature_url: "https://nfo.example.org/observ/fields.yaml.sig" signing_public_key_lookup_url: "key-reg/prod-policy-key" collector: url: "https://telemetry.nfo.example.org/v1/network/events" GitBook AssistantAskCopy governance: effective_from: "2026-03-10T00:00:00Z" effective_until: "2027-03-10T00:00:00Z" signed: true --- # Publish API Performance Benchmarking | Beckn Networks | NFH Fabric The Publish API is the primary entry point for network participants to publish and update their catalogs across the Beckn network. This report presents the measured performance characteristics under realistic catalog workloads. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#at-a-glance) ✨ At a Glance ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#id-1-000) πŸš€ ~1,000 operations/sec Peak throughput #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#id-86-191-ms) ⚑ 86–191 ms P90 latency 1–4 CPU range #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#id-2.52x) πŸ“ˆ 2.52x throughput gain 1 CPU β†’ 4 CPU * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#methodology) πŸ”¬ Methodology -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The benchmarks were conducted under controlled conditions on an isolated environment to ensure consistent, repeatable results. The workload uses a **standard protocol catalog dataset** representative of real-world cross-domain publishing patterns. **150,000** total publish operations were executed across three configurations, based on the following fixed parameters: #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#traffic-simulation) Traffic Simulation Parameter Value **Concurrent Users** `50` virtual users **Total Requests** `50,000` payload submissions #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#payload-anatomy) Payload Anatomy Parameter Value **Payload Size** `~52 KB` (average) **Catalog Density** `2` Catalogs per request **Resources per Catalog** `50` Resources & `10` Offers **Total Resources per Request** `100` * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#results) πŸ“ˆ Results ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Three service configurations were tested, each with increasing compute (CPU) allocation. Memory was held constant at 1 GB to isolate the effect of compute scaling. **Reading the latency columns** P90 = 90% of requests completed within that time. P95 and P99 capture the 95th and 99th percentiles β€” the experience of even the slowest requests. πŸš€ Throughput Overview ⚑ Latency Profile βš™οΈ Compute Scaling Configuration CPU Throughput P90 P95 P99 Standard 1 383 req/s 191 ms 204 ms 285 ms Enhanced 2 605 req/s 146 ms 171 ms 236 ms **High Performance** **4** **963 req/s** **86 ms** **106 ms** **150 ms** Comparing the Standard (1 CPU) and High Performance (4 CPU) configurations: Percentile Standard High Performance Improvement P90 191 ms 86 ms **55% faster** πŸš€ P95 204 ms 106 ms **48% faster** πŸš€ P99 285 ms 150 ms **47% faster** πŸš€ Latency improved consistently across all percentiles β€” the gains apply to every request, not just the fastest ones. From 1 CPU to 4 CPU, throughput increased **2.52x** with each doubling of CPU delivering a consistent **~1.6x** gain. Step Gain Efficiency 1 CPU β†’ 2 CPU 1.58x πŸ“ˆ 79% 2 CPU β†’ 4 CPU 1.59x πŸ“ˆ 80% **1 CPU β†’ 4 CPU** **2.52x 🌟** **63%** ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#key-takeaways) 🎯 Key Takeaways * **Highly Scalable:** The service scales predictably with compute resources, achieving near-linear throughput gains with ~80% efficiency per CPU doubling. * **Low Latency:** Even at the 99th percentile, the High Performance configuration handles complex catalog payloads in **150 ms**. * **Memory Efficient:** All configurations ran with just **1 GB memory** β€” even at 963 req/s, memory was not a limiting factor. * **High Reliability:** Zero errors across 150,000 operations demonstrates robust stability under sustained heavy load. * * * Benchmarking data collected on the Beckn Catalog Benchmarking environment using standard catalog payloads representative of production traffic patterns. [PreviousAPI Reference](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/api-reference) [NextBuild Trusted Networks using REGISTR](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr) Last updated 1 month ago Was this helpful? * [✨ At a Glance](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#at-a-glance) * [πŸ”¬ Methodology](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#methodology) * [πŸ“ˆ Results](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#results) * [🎯 Key Takeaways](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/publish-api#key-takeaways) Was this helpful? --- # DeDi 101 | DeDi | NFH Fabric The **DeDi Protocol** defines a universal, open standard for discovering and verifying public information across the internet. It specifies a machine-readable, unified API that enables interoperability and trust in querying and verifying public directories. **DeDi Global** is a hosted implementation of the DeDi (Decentralized Directories) Protocol. Before proceeding, review the core protocol specifications available [here](https://github.com/LF-Decentralized-Trust-labs/decentralized-directory-protocol) to gain a foundational understanding of the DeDi architecture and design principles. Anyone implementing the DeDi Protocol or integrating with DeDi Global must be familiar with its **three-tier architecture** and **API conventions**, which together enable secure and verifiable data discoverability. The **DeDi architecture** is organized into three hierarchical layers: #### [](https://docs.nfh.global/dedi/dedi.global-developers/dedi-101#id-1.-namespace-root-level) 1\. Namespace (Root Level) Represents the root domain or trust anchor. Each namespace corresponds to a domain name and defines the boundary of trust for the registries it manages. Establishing the root of trust is critical; without it, discoverable data lacks contextual integrity. The most common form of identity today is a domain name, which serves as the namespace identifier. Consequently, all DeDi-compliant APIs begin with the namespace identifier. #### [](https://docs.nfh.global/dedi/dedi.global-developers/dedi-101#id-2.-registry-intermediate-level) 2\. Registry (Intermediate Level) A registry represents a logical grouping of records within a namespace. It defines the schema or structure of the data it contains. #### [](https://docs.nfh.global/dedi/dedi.global-developers/dedi-101#id-3.-record-leaf-level) 3\. Record (Leaf Level) Individual entries or data points within a registry. These three entities β€” **namespace**, **registry**, and **record** β€” are tightly coupled. DeDi assumes that a consumer knows which domain (namespace) and registry they intend to query. For example, a person’s SSN could appear in multiple registries depending on context; therefore, querying without specifying the correct namespace and registry may yield meaningless results. [PreviousDeveloper documentation](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation) [NextQuickstart](https://docs.nfh.global/dedi/dedi.global-developers/quickstart) Last updated 1 month ago Was this helpful? Was this helpful? --- # Glossary | DeDi | NFH Fabric Key Description **Namespace** Root domain or trust anchor **Registry** Logical grouping of records within a namespace **Record** Individual data entry in a registry **Version ID** Identifier representing a specific historical state of an entity **DeDi Global** SaaS implementation of the DeDi Protocol **namespace\_id** Each namespace gets a unique identifier when created, it must be used in all the spaces where you see namespace\_id or namespace, after the domain verification, one might use the domain instead of this identitifer **registry\_id** Each registry get a unique identifier when created, It could be used for verification on chain **record\_id** Each record get a unique identifier when created, It could be used for verification on chain **did** decentralised identifiers. (https://www.w3.org/TR/did-1.0/) for more details [PreviousFAQs](https://docs.nfh.global/dedi/miscellaneous/faqs) Last updated 1 month ago Was this helpful? Was this helpful? --- # The vision for Decentralised Directory (DeDi) | DeDi | NFH Fabric #### [](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi#decentralized-directory-dedi-enhancing-trust-in-digital-transactions) Decentralized Directory (DeDi): Enhancing Trust in Digital Transactions **The Problem: Slow, Expensive Verification. High-cost of establishing trust!** > _DeDi solves costly verification problems. Businesses spend time and resources checking if documents, credentials, and data are valid. DeDi creates a universal way to verify public information instantly._ Every day, people carry out millions of digital transactions, which underpin the global economy. Establishing trust by verifying the **integrity, validity, and authenticity** of documents, digital credentials, transactions, or data packets is paramount for seamless execution of these transactions**. While integrity can often be verified through digital signatures, ensuring validity** (is the information current, not revoked?) and **authenticity** (is the source trustworthy?) **remains a significant challenge.** _(For details on Integrity, Validity, and Authenticity, refer to β€˜Understanding Trust Pillars’ in Appendix)_ In our interconnected digital world, trust is established through public information maintained by custodians, registrars, and institutions of authority. These are often referred to as public directories – specialized electronic registries containing publicly available information about entities and things. Examples include directories of companies, banks, courts, language codes, location codes, directories of registered professionals (e.g., doctors, lawyers), a directory of government-authorized service providers, and more such directories. Historically, even "Yellow Pages" served as a form of public directory. Currently, establishing this trust involves: * **Inefficient Processes, leading to Higher Costs:**
Organizations spend excessive time and resources manually searching for and verifying critical information. These outdated methods can slow down operations, increase labor costs, and introduce errors that damage reliability. * **Risk of Bad Decisions due to Delayed or Outdated Information:** 
When up-to-date information isn’t readily available, businesses may miss important updates (like revoked credentials), potentially making wrong decisions or exposing themselves to fraud and security risks. * **Difficult Integrations result in Missed Opportunities and Slower Growth:**
Inconsistent and custom-built interfaces make it hard for businesses to connect with multiple registries. This adds integration costs, delays time-to-market, and hinders innovation or expansion into new markets where interoperability is key. DeDi overcomes these challenges by transforming fragmented and inefficient registriesβ€”whether manual or digitalβ€”into programmable, agent-ready directories. This empowers businesses with instant access to reliable information, streamlined processes, and seamless integration for the demands of the digital age. It provides a unified, machine-readable interface for accessing essential public information, fostering secure and efficient digital transactions. **Decentralized Directory Protocol – universal way to discover & verify public information** **DeDi is a project under** [**Linux Foundation Decentralised Trust (LFDT)**](https://www.lfdecentralizedtrust.org/) **as part of their** [**LFDT labs**](https://lf-decentralized-trust-labs.github.io/labs/lfdt/decentralized-directory-dedi.html) **initiatives.** DeDi unlocks new business value by making public directories accessible through a universal protocol coupled with suggested practices. > _At its core,_ _**DeDi is an open protocol that defines universal, standardized API specifications for accessing any public registry, enabling seamless lookup and querying across diverse information sources.**_ _By providing open-source API specifications, DeDi eliminates the need for costly custom integrations, allowing registrars to implement a unified and consistent interface for public information access._ DeDi doesn't necessitate changes to existing processes but implements characteristics that make public directories suitable for enhancing trust at a low cost such as: * **Publicly Accessible:** Allows anyone to look up specific records or query for multiple records, promoting transparency and broad usability. * **Machine-Readable:** Accessible over standard APIs (HTTPS, RESTful) with well-known schemas for easy programmatic interpretation and automation. * **Tamper-Resistant:** Offers cryptographic guarantees to ensure the immutability and verifiability of records, enabling a "trust, but verify" approach. * **Provenance-Enabled:** Provides authorship of entries and a history of changes, allowing access to earlier versions for transparency and auditability. * **Live and Frequently Updated:** Ensures that information such as membership statuses, sanctions, and public keys is always up-to-date, reducing risks associated with outdated data. Business Value How It Helps Your Business Capability Enabling It Instantly access reliable information Make faster, more accurate business decisions with confidence Machine-Readable APIs: Standardized, programmable access Know the source and history of every record Simplify compliance and increase transparency Provenance Tracking & Audit Trails: Recorded authorship and change history Trust your data and protect against fraud Strengthen security and customer trust Cryptographic Tamper-Resistance: Immutable, verifiable records Find and use the data you need, without barriers Improve efficiency and serve more customers easily Public, Interoperable Interfaces: Uniform, open access Minimize costs and future-proof your operations Stay agile and ready for growth with seamless integration Compatibility Layers & Modular Integration: Works with current systems Always make decisions based on the latest information Reduce risk by avoiding outdated or incorrect data Live Sync & Frequent Updates: Real-time or near-real-time record updates dedi.global – ready to use solution[](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi#dedi.global-ready-to-use-solution) _To accelerate and simplify adoption,_ [_dedi.global_](http://dedi.global/) _, is offered by the_ [_Network for Humanity Foundation_](https://networksforhumanity.org/) _as a ready to use, Universal Digital Infrastructure, in alignment with DPI (digital public infrastructure)_ [_principles_](https://docs.cdpi.dev/the-dpi-wiki/dpi-tech-architecture-principles) _. This philanthropic initiative allows registrars to effortlessly publish and manage their directories on a robust decentralized infrastructure, leveraging blockchain for automated governance, scalability, and enhanced trustβ€”complementing and fully aligned with the open DeDi protocol._ [Read more](https://github.com/nfh-trust-labs/docs/blob/main/documentation/resources/dedi.global) [PreviousUse DeDi in your workflows](https://docs.nfh.global/dedi/about/use-dedi-in-your-workflows) [NextAppendix: Three types of verification](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/appendix-three-types-of-verification) Last updated 1 month ago Was this helpful? Was this helpful? --- # User Guide - DeDi.Global namespace & directory creation | DeDi | NFH Fabric DeDi.global is a ready-to-use SaaS implementing the open DeDi protocol, offered by the Networks for Humanity Foundation. It allows registrars to publish and manage public registries on a decentralized infrastructure. RECAP - Core Concepts[](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#recap-core-concepts) * **Namespace** β€” corresponds to a domain (and its organisation). Think of it as the digital "root" under which all directories and records live. Users can own multiple namespaces, similar to owning multiple domains. * **Directory (Registry)** β€” a list of records with a configurable schema, sitting under a namespace. The terms _directory_ and _registry_ are interchangeable. * **Record** β€” an individual entry within a directory, structured according to the directory's schema. ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-1.-account-setup) 1\. Account Setup 1. **Register** at [publish.dedi.global](https://publish.dedi.global/) with any email address. 2. **Verify your account** β€” click the authentication link sent to your email. 3. **Log in** β€” returning users authenticate via password + a one-time email link (MFA). 4. **Generate an API Key** _(optional)_ β€” for secure programmatic access via the DeDi APIs. ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-2.-namespace-setup) 2\. Namespace Setup 1. **Create a Namespace** β€” provide a name and description via the dashboard or API. 2. **Verify the Namespace** _(optional but recommended)_ β€” linking a namespace to a domain gives it "verified" status and makes its contents publicly accessible. compass **Domain Verification Steps** 1. **Request domain whitelisting** β€” submit your domain [here](https://docs.google.com/forms/d/e/1FAIpQLScAwEZh94DCIw70zrxWUJ1cud_wYfo_WEjqDpEmbxaw5ZF9aw/viewform?usp=dialog) . Requests are processed within ~5 minutes if no adverse signals are detected. 2. **Get the TXT record** β€” a DNS TXT record is generated for your domain. 3. **Update DNS** β€” add the generated TXT record to your domain's DNS configuration. 4. **Click "Verify"** β€” confirm verification once the DNS update has propagated. ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-3.-registry-and-records) 3\. Registry & Records 1. **Create a Registry** β€” provide a name, description, and select a schema template. * Available templates: **Membership**, **Public Key**, **Revocation**, **Beckn schemas**. * Custom schemas can be provided via JSON Schema Draft 7 (ideally published on a standard like schema.org). 2. **Add Delegates** _(optional)_ β€” assign delegates to help manage the registry. 3. **Add Records** β€” create entries in the registry per the selected schema. ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-4.-ongoing-management) 4\. Ongoing Management You can update **namespace details**, **registry details**, and **record details** at any time through the dashboard or APIs. State management options are available for both registries and records. ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-5.-accessing-data) 5\. Accessing Data Use the **Standard APIs** to query and manage data. Refer to the [API reference](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis) section for usage patterns and sample implementations. πŸ“Ή **Video walkthrough** β€” [Loom demo](https://www.loom.com/share/e0293309701348dc95719a98b957d12c?sid=04b8dc00-51de-46ac-82ce-adc1a0060409) [PreviousQuickstart](https://docs.nfh.global/dedi/dedi.global-developers/quickstart) [NextSetup for using DeDi APIs](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/setup) Last updated 1 month ago Was this helpful? * [1\. Account Setup](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-1.-account-setup) * [2\. Namespace Setup](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-2.-namespace-setup) * [3\. Registry & Records](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-3.-registry-and-records) * [4\. Ongoing Management](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-4.-ongoing-management) * [5\. Accessing Data](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/namespace-and-registry-creation#id-5.-accessing-data) Was this helpful? --- # Watch Feature | DeDi | NFH Fabric Similar to the **Subscribe** feature you see on platforms like YouTubeβ€”where you get instant notifications about updates from channels you followβ€”**DeDi** offers a powerful way to stay informed through its **Watch** feature. ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature#what-is-watch) πŸ”” What is Watch? The **Watch** feature in DeDi allows you to subscribe to changes across different entities in the system. When an event occurs, you receive a notification instantly, helping you stay up-to-date with the latest activity. ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature#types-of-watch) 🧭 Types of Watch #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature#id-1.-registry-watch) 1\. Registry Watch Keep a watch on a specific **registry** to get notified when: * Registry details are updated * A new entry or record is added * An existing entry or record is modified #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature#id-2.-tag-watch) 2\. Tag Watch Keep a watch on a specific **tag** to get notified when: * A registry is created using that tag * An existing registry updates its tag to the one you are watching #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature#id-3.-record-watch) 3\. Record Watch Keep a watch on a specific **record** to get notified when: * The record details are updated or modified The **Watch** feature makes DeDi more interactive and connectedβ€”helping you monitor changes that matter most to you, in real time. [PreviousState management](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management) [NextAPI Tools & Resources](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools) Last updated 1 month ago Was this helpful? * [πŸ”” What is Watch?](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature#what-is-watch) * [🧭 Types of Watch](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature#types-of-watch) Was this helpful? --- # Schema Registry on DeDi | DeDi | NFH Fabric [](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi#the-problem) The Problem ------------------------------------------------------------------------------------------------------------------------ APIs and data formats evolve. Schemas are documented in PDFs, wikis, or version-controlled repos that consumers may not know about. When a schema changes, consumers have no reliable discovery mechanism. Deprecated schemas linger. New schemas go unnoticed. Integration breaks are discovered in production. [](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi#the-dedi-solution) The DeDi Solution ------------------------------------------------------------------------------------------------------------------------------------ Publish API and data schemas as versioned, resolvable records on DeDi. Each schema record contains: the schema definition (JSON Schema, XML Schema, or any structured format), a namespace URI, version identifiers, deprecation status, and links to successor schemas. Consumers discover schemas via the same API they use for every other DeDi registry. #### [](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi#how-it-works) How It Works Publish Organization publishes schemas to a DeDi namespace. Each schema is a record with the schema body, version, status (active/deprecated/superseded), and a namespace URI. Discover Developers query the DeDi registry to find all schemas for a namespace, filter by status (active only, or including deprecated), and retrieve specific versions. Version When a schema evolves, a new version is published. The old version’s record is updated to point to the successor. Both remain resolvable. Resolve Any system can dereference a schema’s namespace URI to get the full schema definition from DeDi. Machine-readable, cryptographically verified. [](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi#what-changes) What Changes -------------------------------------------------------------------------------------------------------------------------- Before DeDi After DeDi Schemas in PDFs, wikis, scattered repos Single registry with all schemas, versions, and deprecation status No machine-readable discovery Query API to find active schemas, resolve by namespace URI Breaking changes discovered in production Deprecation status and successor links enable graceful migration No cryptographic provenance β€” who published this version? Every schema version is signed, timestamped, and anchored on-chain [PreviousRevocation Registry on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi) [NextVC Signing Keys on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi) Last updated 1 month ago Was this helpful? * [The Problem](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi#the-problem) * [The DeDi Solution](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi#the-dedi-solution) * [What Changes](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi#what-changes) Was this helpful? --- # Features of DeDi.global | DeDi | NFH Fabric ### [](https://docs.nfh.global/dedi/resources/dedi.global/features-of-dedi.global#cryptographic-trust) **Cryptographic Trust** **On-chain anchoring** _Every namespace, registry, and record is anchored on the CORD blockchain (BLAKE2 H256). Any change creates an immutable, auditable trail that can be verified directly on-chain._ **Provenance** _Each entry carries a verifiable chain of authorship: who published it, when, and under which namespace. DID Documents are auto-generated for every profile._ **Tamper evidence** _Any modification β€” even by the publisher β€” generates a new version with its own proof. Historical states remain verifiable through the API and on-chain._ ### [](https://docs.nfh.global/dedi/resources/dedi.global/features-of-dedi.global#lifecycle-management) Lifecycle management **Versioning** _Every change creates a new version. Full history is accessible via the Versions API. Historical lookups via the as\_on date parameter retrieve the state at any point in time._ [](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management) **State management** _Namespaces remain live, registries move between live and inactive, and records move from draft to live. Deleted entities remain recoverable during the restore window before permanent archival._ [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/subscription) **Watch & Subscribe** _Real-time notifications when registries, records, or tags change. Subscribe to a namespace/ registry/ registry schema for alerts on new or modified records._ [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation) **Delegation** _Grant management permissions to other DeDi users at namespace or registry level. Delegates can publish and manage records on behalf of the owner._ **Schema design** _Configurable schemas define entry structure and types. Schemas are versioned and machine-readable, enabling automated validation._ [](https://docs.nfh.global/dedi/resources/dedi.global/features-of-dedi.global#zero-lock-in-by-design) Zero Lock-in by Design --------------------------------------------------------------------------------------------------------------------------------- Every design decision ensures adopters bear zero switching cost and zero platform risk: **Open protocol** DDP is an open spec under LFDT. Anyone can implement it. DeDi.global is one implementation β€” not the only one. Records are interoperable across all nodes. **Full data portability** Standard JSON with W3C-aligned proofs. Export your namespace and host it elsewhere at any time. **No fees, no contracts** Free to publish, free to query. No licensing. No exit clause. Stop anytime. [PreviousDeDi.global](https://docs.nfh.global/dedi/resources/dedi.global) [NextRepresentative Use Cases](https://docs.nfh.global/dedi/resources/representative-use-cases) Last updated 1 month ago Was this helpful? * [Cryptographic Trust](https://docs.nfh.global/dedi/resources/dedi.global/features-of-dedi.global#cryptographic-trust) * [Lifecycle management](https://docs.nfh.global/dedi/resources/dedi.global/features-of-dedi.global#lifecycle-management) * [Zero Lock-in by Design](https://docs.nfh.global/dedi/resources/dedi.global/features-of-dedi.global#zero-lock-in-by-design) Was this helpful? --- # How to Use DeDi | DeDi | NFH Fabric DeDi turns any public registry β€” entity lists, public keys, schemas, credential status β€” into machine-readable, cryptographically verifiable records accessible via a single API. All data on DeDi is public data. There is no vendor lock-in: the protocol is open, the data is portable, and you can leave at any time. > _To accelerate and simplify adoption,_ [_dedi.global_](http://dedi.global/) > _, is offered by the_ [_Network for Humanity Foundation_](https://networksforhumanity.org/) > _as a ready to use, Universal Digital Infrastructure, in alignment with DPI (digital public infrastructure)_ [_principles_](https://docs.cdpi.dev/the-dpi-wiki/dpi-tech-architecture-principles) > _. This philanthropic initiative allows registrars to effortlessly publish and manage their directories using an open, on chain infrastructure, β€”complementing and fully aligned with the open DeDi protocol._ [](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#choose-your-path) Choose Your Path --------------------------------------------------------------------------------------------------------------------------------------------- **Option A: Publish on DeDi.global + mirror on your own website**[](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#option-a-publish-on-dedi.global--mirror-on-your-own-website) > _Recommended as phase 0 β€” Best of both worlds_ Publish your registries on DeDi.global (free, instant, zero infrastructure) and embed the same data on your own website via DeDi’s API or widget. Your users get the convenience of your existing site AND the cryptographic guarantees of DeDi. If you ever want to stop using DeDi.global, your website continues to serve the data β€” you just lose the on-chain anchoring until you point to another node. Setup effort Minutes. Create a namespace, publish records via API or dashboard. Embed widget or API calls on your site. Infrastructure cost Zero. DeDi.global is free. Your website is already running. Maintenance Zero on the DeDi side. NFH operates and maintains DeDi.global. Lock-in risk None. Data is portable. Protocol is open. You can export and leave at any time. What you get Tamper-proof records, on-chain anchoring, versioning, cryptographic proofs, sub-200ms API, revocation infrastructure β€” all without running a single server. **Option B: Publish on DeDi.global only**[](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#option-b-publish-on-dedi.global-only) > Simplest, safe path β€” Zero infrastructure, zero maintenance Publish your registries directly on DeDi.global. Anyone can query them via the DeDi API. You don’t need to build, host, or maintain anything. This is the fastest way to make your public data machine-readable and verifiable. Ideal for organizations that currently distribute data as PDFs, spreadsheets, or static web pages and want to modernize without any engineering effort. Setup effort Minutes. Create a namespace, publish records. Done. Infrastructure cost Zero. Maintenance Zero. Lock-in risk None. Same portability guarantees as Option A. Trade-off Your existing website doesn’t serve the data directly - consumers use the DeDi API. You can add website integration later at any time. **Option C: Spin up your own DeDi node**[](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#option-c-spin-up-your-own-dedi-node) > Maximum control β€” For organizations with specific infrastructure requirements Deploy the open-source DeDi protocol on your own infrastructure. You run the node, you control the data, you manage the uptime. Records anchored on your node are interoperable with DeDi.global and any other DeDi node β€” the protocol is the same everywhere. This option is for organizations that have regulatory, sovereignty, or policy reasons to self-host. Setup effort Weeks to Months. Requires DevOps capacity to deploy and configure the node and capacity to ensure transparent cryptographic validity Infrastructure cost Hosting, monitoring, and maintenance costs. Maintenance Ongoing. You are responsible for uptime, security patches, and upgrades. Lock-in risk None. Same open protocol. You can migrate to DeDi.global or another node at any time. When to choose this Only if you have a hard requirement to self-host. For most organizations, Option A or B delivers the same guarantees with zero operational burden. [](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#at-a-glance) At a Glance ----------------------------------------------------------------------------------------------------------------------------------- Metric Option A: DeDi.global + Your Site Option B: DeDi.global Only Option C: Own Node Setup time Minutes Minutes Weeks - Months Infrastructure cost Zero Zero You pay Maintenance Zero Zero You maintain On-chain anchoring βœ“ βœ“ Depends on your implementation Cryptographic proofs βœ“ βœ“ Depends on your implementation Revocation registry βœ“ βœ“ βœ“ Sub-200ms API βœ“ βœ“ Depends on your infra Data on your domain βœ“ ✘ βœ“ Data portability Full Full Full [](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#the-bottom-line) The Bottom Line ------------------------------------------------------------------------------------------------------------------------------------------- Your data is already public. DeDi makes it trustworthy and discoverable. If you publish public registries today β€” entity lists, public keys, schemas, credential status, authorization records β€” they are already meant to be accessible. The question is not whether to share them, but whether consumers can trust what they find. DeDi.global adds cryptographic proof, tamper-evidence, versioning, and a universal API to data you are already publishing. It costs nothing, requires no infrastructure, creates no vendor dependency, and can be reversed at any time. For most organizations, Option A (DeDi.global + your website) or Option B (DeDi.global only) is the obvious starting point. You can always upgrade to a self-hosted node later if your requirements demand it. [PreviousAppendix: Three types of verification](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/appendix-three-types-of-verification) [NextDeDi.global](https://docs.nfh.global/dedi/resources/dedi.global) Last updated 1 month ago Was this helpful? * [Choose Your Path](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#choose-your-path) * [At a Glance](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#at-a-glance) * [The Bottom Line](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi#the-bottom-line) Was this helpful? --- # Subscription & Distribution | Beckn Networks | NFH Fabric This guide covers how Discovery Services (DS) subscribe to catalog updates from the Catalog Service (CATALG), receive catalogs via real-time push, and retrieve existing catalogs in bulk via the pull API. > For the overview and end-to-end sequence, see [Publish Catalogs using CATALG](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg) > . For catalog structure, types, directives, and publishing rules, see [Catalog Concepts](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts) > . For exact endpoint shapes and field-level reference, see [API Reference](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/api-reference) > . * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#how-catalogs-reach-discovery-services) How Catalogs Reach Discovery Services --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Publishing to CATALG does not directly make a catalog searchable. A Discovery Service (DS) must first subscribe to CATALG. From that point forward, every accepted catalog publish is automatically pushed to all DS instances whose subscription filters match. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#real-time-push-subscription-driven) Real-Time Push (Subscription-Driven) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A Discovery Service subscribes to CATALG once using `POST /catalog/subscription`, declaring which `networkIds` and/or `schemaTypes` it wants to receive. CATALG matches every accepted publish against active subscriptions and delivers matching catalogs to each DS via `POST /catalog/push`. The DS makes the data immediately available for discovery. GitBook AssistantAskCopy Provider Node ──POST /catalog/publish──► CATALG β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β–Ό β–Ό β–Ό DS (sub A) DS (sub B) DS (sub C) POST /catalog/push POST /catalog/push POST /catalog/push Subscription filters narrow which catalogs a DS receives. At least one of `networkIds` or `schemaTypes` must be provided. An empty `schemaTypes` array matches all schema types for the subscribed networks. GitBook AssistantAskCopy { "context": { "version": "2.0.0", "action": "catalog/subscription", "messageId": "a1b2c3d4-0000-0000-0000-000000000001", "transactionId": "a1b2c3d4-0000-0000-0000-000000000002", "timestamp": "2026-05-27T08:00:00.000Z", "bapId": "ds.local-retail.net", "bapUri": "https://ds.local-retail.net" }, "message": { "subscription": { "networkIds": ["local-retail.net/grocery-net"], "schemaTypes": ["https://schema.beckn.io/RetailResource/2.1/context.jsonld"] } } } CATALG responds synchronously with a `subscriptionId` and `status: ACTIVE`: When a DS is newly deployed or needs to populate from scratch, it uses `POST /catalog/pull` to retrieve all catalogs currently available in CATALG that match its active subscription. CATALG responds asynchronously via `POST /catalog/on_pull`, delivering the full set of matching catalogs. The DS uses this to populate its catalog store before the live subscription stream takes over. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#catalog-pull-bulk-retrieval) Catalog Pull (Bulk Retrieval) --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- `POST /catalog/pull` is how a Discovery Service requests all existing catalogs from CATALG in one operation. It is the mechanism for initial data population and for re-synchronising after an outage. The pull is **fully asynchronous**: 1. DS sends `POST /catalog/pull` β†’ receives immediate ACK 2. CATALG assembles the matching catalogs in the background 3. CATALG delivers results to the DS via `POST /catalog/on_pull` on the DS's `bapUri` 4. DS processes the received catalogs and makes them available for discovery The pull request is **scoped to an existing active subscription** β€” the `subscriptionId` is required, and CATALG uses that subscription's `networkIds` and `schemaTypes` to determine which catalogs to return. A DS must have an active subscription before issuing a pull. > **Ownership enforced:** A DS can only pull using a `subscriptionId` it owns. Attempting to pull with another subscriber's `subscriptionId` returns a 403. If the `subscriptionId` does not exist, a 404 is returned. CATALG responds immediately with an ACK and then delivers results asynchronously to `POST /catalog/on_pull` on the caller's `bapUri`. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#callback-inline-payload) Callback β€” Inline Payload When the result set is small, CATALG delivers the catalogs inline in the `catalogs` array: ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#callback-large-payload-download-manifest) Callback β€” Large Payload (Download Manifest) When the result is too large to return inline, CATALG returns a `downloadManifest` instead. The DS must download the payload from the provided URL, verify the checksum, and then process the content. Field Description `url` Pre-signed download URL. The DS must not attempt download after `expiresAt` `expiresAt` Expiry timestamp β€” if expired, re-issue `POST /catalog/pull` `format` `json` or `json.gz` β€” decompress before parsing if `json.gz` `sizeBytes` Payload size in bytes; the DS may use this to verify download completeness `checksum` `sha256:` prefixed hex digest β€” the DS must verify before processing; discard and treat as failed if verification fails > `**catalogs[]**` **and** `**downloadManifest**` **are mutually exclusive.** Exactly one must be present when `status` is `COMPLETED`. When `status` is `FAILED`, neither is present β€” read the `error` field instead. * * * **Next:** [API Reference β†’](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/api-reference) [PreviousCatalog Concepts](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts) [NextAPI Reference](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/api-reference) Last updated 9 days ago Was this helpful? * [How Catalogs Reach Discovery Services](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#how-catalogs-reach-discovery-services) * [Real-Time Push (Subscription-Driven)](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#real-time-push-subscription-driven) * [Catalog Pull (Bulk Retrieval)](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#catalog-pull-bulk-retrieval) * [Callback β€” Inline Payload](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#callback-inline-payload) * [Callback β€” Large Payload (Download Manifest)](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution#callback-large-payload-download-manifest) Was this helpful? GitBook AssistantAskCopy { "context": { "version": "2.0.0", "action": "catalog/on_subscription", "messageId": "a1b2c3d4-0000-0000-0000-000000000001", "transactionId": "a1b2c3d4-0000-0000-0000-000000000002", "timestamp": "2026-05-27T08:00:00.100Z" }, "message": { "subscriptions": [\ {\ "subscriptionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",\ "status": "ACTIVE",\ "networkIds": ["local-retail.net/grocery-net"],\ "schemaTypes": ["https://schema.beckn.io/RetailResource/2.1/context.jsonld"],\ "createdAt": "2026-05-27T08:00:00.000Z",\ "updatedAt": "2026-05-27T08:00:00.000Z"\ }\ ] } } GitBook AssistantAskCopy { "context": { "version": "2.0.0", "action": "catalog/pull", "messageId": "e1f2a3b4-0000-0000-0000-000000000099", "transactionId": "e1f2a3b4-0000-0000-0000-000000000100", "timestamp": "2026-05-27T10:00:00.000Z", "bapId": "ds.local-retail.net", "bapUri": "https://ds.local-retail.net" }, "message": { "subscriptionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "mode": "FULL", "limit": 20, "offset": 0 } } GitBook AssistantAskCopy { "message": { "status": "ACK", "messageId": "e1f2a3b4-0000-0000-0000-000000000099" } } GitBook AssistantAskCopy { "context": { "version": "2.0.0", "action": "catalog/on_pull", "messageId": "e1f2a3b4-0000-0000-0000-000000000099", "transactionId": "e1f2a3b4-0000-0000-0000-000000000100", "timestamp": "2026-05-27T10:01:05.000Z", "requestDigest": { "digest": "BLAKE-512=mB2c5x...base64..." } }, "message": { "status": "COMPLETED", "catalogs": [ ... ], "pagination": { "total": 12, "limit": 20, "offset": 0 } } } GitBook AssistantAskCopy { "context": { "version": "2.0.0", "action": "catalog/on_pull", "messageId": "e1f2a3b4-0000-0000-0000-000000000099", "transactionId": "e1f2a3b4-0000-0000-0000-000000000100", "timestamp": "2026-05-27T10:01:05.000Z", "requestDigest": { "digest": "BLAKE-512=mB2c5x...base64..." } }, "message": { "status": "COMPLETED", "downloadManifest": { "url": "https://storage.example.com/catalog-pull-results/e1f2a3b4.json.gz?token=...", "expiresAt": "2026-05-27T11:01:05.000Z", "format": "json.gz", "sizeBytes": 4823104, "checksum": "sha256:a3f1e9b7c2d04..." }, "pagination": { "total": 1450, "limit": 20, "offset": 0 } } } --- # Representative Use Cases | DeDi | NFH Fabric DeDi.global can be used to host any public list or registry. Users are free to define their own schema on DeDi.global to suit their use cases. A few common examples are listed below. _(Click on each card to know more)_ [](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi) Type of registry **Public keys** Impact Instant key discovery. Rotation propagates via Watch. No stale certificates. [](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi) Type of registry **Revocation** Impact Universal revocation for XML, QR, VCs. Single API call (& optional cache) to check status. [](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi) Type of registry **VC signing keys** Impact Global key resolution in one call. Historical lookup for older credentials. [](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi) Type of registry **Authorized entities** Impact Programmatic authorization checks. Revocations visible immediately. [](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi) Type of registry **Schemas** Impact Machine-readable discovery. Verifiers validate against exact versions. [PreviousFeatures of DeDi.global](https://docs.nfh.global/dedi/resources/dedi.global/features-of-dedi.global) [NextPublic Key Registry on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi) Last updated 1 month ago Was this helpful? Was this helpful? --- # VC Signing Keys on DeDi | DeDi | NFH Fabric Globally resolvable issuer keys for the Verifiable Credentials ecosystem [](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi#the-problem) The Problem ------------------------------------------------------------------------------------------------------------------------ When an organization issues Verifiable Credentials, verifiers need the issuer’s public signing key to validate the credential’s signature. Today, these keys are scattered β€” buried in DID documents, hosted on proprietary resolvers, or distributed through bilateral agreements. There is no universal, standards-based way for a verifier to resolve an issuer’s VC signing keys without knowing the issuer’s specific infrastructure. [](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi#the-dedi-solution) The DeDi Solution ------------------------------------------------------------------------------------------------------------------------------------ Publish VC signing keys (Ed25519, BBS+, SD-JWT, ECDSA) as structured records on DeDi. Any verifier globally can resolve an issuer’s keys in one API call, regardless of the credential format or the issuer’s DID method. #### [](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi#how-it-works) How It Works Publish keys Issuer publishes their VC signing public keys to a DeDi namespace. Each key record includes: algorithm (Ed25519, BBS+, etc.), public key material, purpose (assertionMethod, authentication), and validity period. Resolve Verifier calls DeDi Lookup or Query API with the issuer’s namespace and key ID. Returns the key with cryptographic proof. Rotate When keys are rotated, new versions are published. Old keys remain resolvable for historical credential verification. Multi-format A single issuer can publish keys for multiple credential formats (JSON-LD with Data Integrity, JWT, SD-JWT) in the same namespace. #### [](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi#what-this-enables) What This Enables Any verifier, anywhere in the world, can validate a Verifiable Credential from any issuer that publishes on DeDi β€” without bilateral integration, without knowing the issuer’s DID method, and without relying on the issuer’s infrastructure being online at verification time. This is particularly critical for cross-border credential verification, where issuers and verifiers operate under different technical stacks and trust frameworks. #### [](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi#example) Example GitBook AssistantAskCopy GET https://dedi.global/dedi/lookup/{issuer-namespace}/{signing-keys}/{key-id} Returns: JSON with public key material (JWK or PEM), algorithm identifier, purpose, validity dates, version history, on-chain proof. [PreviousSchema Registry on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi) [NextDeDi in Verifiable Credential Workflows](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows) Last updated 1 month ago Was this helpful? * [The Problem](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi#the-problem) * [The DeDi Solution](https://docs.nfh.global/dedi/resources/representative-use-cases/vc-signing-keys-on-dedi#the-dedi-solution) Was this helpful? --- # Domain Verification - The bedrock of trust in DeDi | DeDi | NFH Fabric ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#why-verify-a-domain) Why Verify a Domain? Domain verification helps establish trust and provides several benefits: * Makes your namespace identifiers human-readable * Establishes clear provenance of data * Associates your namespace with a verified domain name * Improves the readability and trustworthiness of API interactions ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#example) Example #### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#before-domain-verification) Before Domain Verification GitBook AssistantAskCopy GET dedi/76EU7hbHV3aEnjjMZKTrPqbudeYrymjYR761h6v6egEe6JMjnkU6HT/employees/Alice #### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#after-domain-verification) After Domain Verification GitBook AssistantAskCopy GET dedi/dhiway.com/employees/Alice The verified domain makes the URL human-readable and helps establish clear provenance of the data. ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#verification-process) Verification Process #### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#prerequisites) Prerequisites * A registered domain name that you control * Access to your domain's DNS settings * A namespace ID of the namespace you created #### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#steps) Steps 1. **Domain Whitelisting** * Submit a request [here](https://docs.google.com/forms/d/e/1FAIpQLScAwEZh94DCIw70zrxWUJ1cud_wYfo_WEjqDpEmbxaw5ZF9aw/viewform?usp=dialog) to whitelist your domain 2. **Generate a Verification Record** * Use our API/UI to generate the verification value * Supported verification methods are `self_dns`, `self_http`, and `request_other_namespace` 3. **DNS Configuration** * Add the provided TXT record to your domain's DNS settings * Wait for DNS propagation (can take anywhere from 15 min to 48 hours) 4. **Verify Domain** * Use either the UI or API to complete verification API Endpoint: Request Body: Verification checks DNS TXT first and falls back to `https:///.well-known/dedi-verification.txt` for HTTP-based verification. 5. **Re-verification lifecycle** * Verified domains are re-checked on a scheduled basis * The current implementation re-verifies active sources after a configurable interval with a default of `1` year * Failed sources enter a configurable grace period with a default of `7` days before the source is removed 6. **Delegated verification decisions** * Target namespace delegates use the verification-request and notification APIs to accept or reject delegated verification requests ### [](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#whats-next) What's Next? After verification, you can: * Use your domain name instead of namespace ID in all API calls * Establish stronger trust with your data consumers * Create a more professional and polished API experience [PreviousSetup for using DeDi APIs](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/setup) [NextAPI Reference](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis) Last updated 1 month ago Was this helpful? * [Why Verify a Domain?](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#why-verify-a-domain) * [Example](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#example) * [Verification Process](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#verification-process) * [What's Next?](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi#whats-next) Was this helpful? GitBook AssistantAskCopy GET dedi/generate-dns-txt/{{namespace_id}}/{{domain}}?verification_method=self_dns GitBook AssistantAskCopy POST /dedi/verify-domain GitBook AssistantAskCopy { "namespace_id": "string" } --- # Registry Service Performance Benchmarking | Beckn Networks | NFH Fabric This page summarizes a set of performance tests conducted on the Registry Service in December 2025 to understand how it behaves under different data sizes and infrastructure configurations. **The goal is to give operators a practical sense of the throughput and latency they can expect under different data sizes and load levels.** The results below are based on sustained load tests using the open-source **k6** tool and reflect steady-state behavior rather than short-lived spikes. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#at-a-glance) ✨ At a Glance ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#id-2-200) πŸš€ ~2,200 requests/sec Peak throughput ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#id-42-ms) ⚑ ~42 ms p95 latency At peak throughput ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#id-2x) πŸ“ˆ ~2x throughput gain 2 vCPU β†’ 4 vCPU * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#test-methodology) πŸ”¬ Test Methodology ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Benchmarks were run under controlled conditions using **k6** virtual users against a live Registry Service instance. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#traffic-simulation) Traffic Simulation Parameter Value **Concurrent Users** 50–100 virtual users **Duration** 10 minutes (R0: 2 minutes) #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#infrastructure-configurations-tested) Infrastructure Configurations Tested Config Memory vCPU Small 4 GB 2 Medium 8 GB 2 Large 16 GB 4 #### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#dataset-shapes-tested) Dataset Shapes Tested Namespaces Registries / Namespace Records / Registry Total Records 500 1 200 100,000 2,000 2 100 400,000 2,000 2 200 800,000 3,000 2 250 1,500,000 1,500 2 500 1,500,000 All reported values represent **steady-state performance**. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#run-results) πŸ“ˆ Run Results ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ **Reading the latency columns** p90 = 90% of requests completed within that time. p95 captures the 95th percentile β€” the experience of nearly all requests, including slower ones. # Thread Count Namespaces Registries / Namespace Records / Registry Total Records Duration Memory CPU Iterations TPS Avg (ms) Min (ms) Med (ms) Max (ms) p90 (ms) p95 (ms) R0 50 500 1 200 100,000 2m 4GB 2 123,938 1032.34 48.18 0.31 46.83 286.86 70.71 78.63 R1 50 500 1 200 100,000 10m 4GB 2 656,173 1093.53 45.5 0.32 44.56 284.97 66.21 72.92 R2 50 500 1 200 100,000 10m 8GB 2 696,003 1159.94 42.88 0.29 42.27 175.11 61.88 67.86 R3 100 500 1 200 100,000 10m 8GB 2 693,374 1155.47 86.31 0.3 85.21 523.17 118.7 129.11 R4 50 2,000 2 100 400,000 10m 8GB 2 1,228,847 2048.01 24.17 0.27 23.22 317.04 36.45 40.82 R5 50 2,000 2 200 800,000 10m 8GB 2 676,575 1127.54 44.08 0.3 42.83 1035.82 63.83 70.69 R6 50 2,000 2 200 800,000 10m 16GB 4 1,337,820 2229.62 22.17 0.27 20.84 134.52 36.38 41.82 R7 50 3,000 2 250 1,500,000 10m 16GB 4 1,070,116 1783.44 27.78 0.28 26.56 208.58 43.78 49.46 R8 50 1,500 2 500 1,500,000 10m 16GB 4 575,289 958.75 51.89 0.25 46.45 301.22 87.21 103.98 * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#key-findings) πŸ” Key Findings -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ⚑ Infra Scaling πŸ“¦ Dataset Scale Scaling from 2 to 4 vCPUs on an 800K-record dataset nearly **doubled throughput** while cutting tail latency by over **85%**. Metric 8 GB / 2 vCPU 16 GB / 4 vCPU Improvement Throughput 1,127 TPS 2,229 TPS **~2x** πŸš€ p95 Latency 70.7 ms 41.8 ms **41% faster** πŸš€ Max Latency 1,035 ms 134 ms **87% faster** πŸš€ With well-distributed data, the Registry Service handles **1.5 million records** efficiently on a 16 GB / 4 vCPU instance β€” sustaining **~1,800 TPS** with **p95 under 50 ms**. Records Namespaces TPS p95 Latency 100,000 500 1,159 67.9 ms 800,000 2,000 2,229 41.8 ms 1,500,000 3,000 1,783 49.5 ms The service scales gracefully across dataset sizes β€” even at 15Γ— the baseline record count, throughput stays above **1,700 TPS**. * * * ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#key-takeaways) 🎯 Key Takeaways * **Highly Scalable:** Throughput nearly doubles when scaling from 2 to 4 vCPUs β€” consistent, predictable gains with additional compute. * **Low Latency at Scale:** Even at 800K records, the service sustains ~2,200 TPS with p95 latency of just ~42 ms on a 16 GB / 4 vCPU instance. * **Stable Under Sustained Load:** No latency degradation observed over 10-minute test runs, demonstrating robust steady-state behavior. * **Handles Large Datasets:** With well-distributed data, the service sustains ~1,800 TPS even at 1.5 million records. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#final-note) Final note ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- These results highlight the Registry Service's ability to deliver **consistent, predictable performance under sustained load** across a wide range of dataset sizes and configurations. The service demonstrates clear scaling behavior, improving both throughput and latency as additional CPU and memory are made available. While real-world performance will naturally vary based on data layout and usage patterns, the observed results show that the Registry Service can comfortably **support high-throughput, low-latency workloads** when appropriately sized. Overall, the tests reinforce that the Registry Service is **well-suited for production workloads**, with performance characteristics that scale in a transparent and predictable way. Benchmarking data collected using k6 against the Beckn Registry Service in December 2025. [PreviousBuild Trusted Networks using REGISTR](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr) [NextProve anything using VC on Edge](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/prove-anything-using-vc-on-edge) Last updated 7 days ago Was this helpful? * [✨ At a Glance](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#at-a-glance) * [πŸ”¬ Test Methodology](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#test-methodology) * [πŸ“ˆ Run Results](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#run-results) * [πŸ” Key Findings](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#key-findings) * [🎯 Key Takeaways](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#key-takeaways) * [Final note](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/build-trusted-networks-using-registr/registry-service-benchmark#final-note) Was this helpful? --- # Guides | DeDi | NFH Fabric Practical how-tos for working with DeDi.global. Each guide covers a specific feature with step-by-step instructions and API examples. * [**Schema Design**](https://claude.ai/chat/guides/schema-design) β€” Define registry schemas using pre-built templates or custom JSON Schema (Draft 7). * [**Bulk Upload**](https://claude.ai/chat/guides/bulk-upload) β€” Import records at scale via CSV through the UI or API. * [**Delegation**](https://claude.ai/chat/guides/delegation-guide) β€” Grant management permissions to other DeDi users at the registry level. * [**State Management**](https://claude.ai/chat/guides/state-management) β€” Manage namespace, registry, and record lifecycle including draft publication, registry activation, deletion, and restore. * [**Watch Feature**](https://claude.ai/chat/guides/watch-feature) β€” Subscribe to real-time notifications when registries, records, or tags change. [PreviousLookup Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification) [NextSchema design](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design) Last updated 1 month ago Was this helpful? Was this helpful? --- # Revocation Registry on DeDi | DeDi | NFH Fabric [](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#the-problem) The Problem ---------------------------------------------------------------------------------------------------------------------------- Offline-first credentials β€” QR codes, XML documents, Verifiable Credentials β€” are powerful because they work without calling the issuer at verification time. But this creates a critical gap: once issued, how does a verifier know if a credential has been revoked? Most offline credential systems today have zero revocation mechanism. A revoked credential looks identical to a valid one. [](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#the-dedi-solution) The DeDi Solution ---------------------------------------------------------------------------------------------------------------------------------------- DeDi provides a tamper-proof, publicly queryable revocation registry. When an issuer revokes a credential, they publish the hashed credential identifier to their revocation registry on DeDi. Any verifier, anywhere, can check revocation status with a single API call β€” without contacting the issuer. #### [](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#the-revocation-flow) The Revocation Flow 1\. Issue Issuer creates a credential. The credential’s credentialStatus field points to the DeDi revocation registry (see VC integration below). 2\. Revoke When a credential must be revoked, the issuer publishes the hashed credential UUID to the DeDi registry with status: revoked. The change is cryptographically anchored and timestamped on-chain. 3\. Verify Verifier hashes the credential’s ID, calls the DeDi Lookup API. If the hash is present with revoked status, the credential is no longer valid. If not found, the credential has not been revoked. [](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#w3c-verifiable-credential-revocation) W3C Verifiable Credential Revocation ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ DeDi can support with the W3C VC Data Model 2.0 via the credentialStatus field. When an issuer creates a Verifiable Credential, they embed a DeDi revocation check directly in the credential GitBook AssistantAskCopy "credentialStatus": { "id": "https://dedi.global/dedi/lookup/{namespace}/{registry}/{hashed-cred-uuid}", "type": "dedi", "statusPurpose": "revocation", "statusListCredential": "https://dedi.global/dedi/query/{namespace}/{registry}" } #### [](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#vc-verification-flow-using-dedi) VC Verification Flow Using DeDi Step 1: Receive VC Verifier receives a Verifiable Credential (JSON-LD, JWT, or SD-JWT format) from the holder. Step 2: Validate signature Verifier checks the VC’s cryptographic signature using the issuer’s public key (which can also be resolved from DeDi β€” see Public Key Registry use case). Step 3: Check revocation Verifier reads the credentialStatus.id field from the VC. This is a DeDi Lookup URL. The verifier calls this endpoint. Step 4: Evaluate response If the DeDi API returns a record with status: revoked, the credential is invalid. If the record is not found (404), the credential has not been revoked. The response includes an on-chain proof for auditability. Step 5: Trust decision Verifier now has: (a) signature validity, (b) revocation status, both independently verifiable without contacting the issuer. #### [](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#why-dedi-for-revocation) Why DeDi for Revocation The revocation registry is tamper-proof β€” even the issuer cannot silently un-revoke a credential. All revocation events are on-chain with timestamps. The registry is publicly queryable, so any verifier can check without credentials or API keys. And because it’s on DeDi, it works across credential systems: national IDs, professional licenses, academic certificates, organizational authorizations. [PreviousAuthorized Entity Registry on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi) [NextSchema Registry on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/schema-registry-on-dedi) Last updated 1 month ago Was this helpful? * [The Problem](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#the-problem) * [The DeDi Solution](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#the-dedi-solution) * [W3C Verifiable Credential Revocation](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi#w3c-verifiable-credential-revocation) Was this helpful? --- # Public Key Registry on DeDi | DeDi | NFH Fabric ### [](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi#the-problem) The Problem Organizations distribute public keys β€” encryption keys, signing certificates, TLS root CAs β€” as static files (.cer, .pem, .pub) on websites. Consumers download them manually, cache them locally, and have no reliable way to know when a key has been rotated, revoked, or replaced. Stale keys cause silent verification failures. Manual distribution cannot scale. ### [](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi#the-dedi-solution) The DeDi Solution Publish public keys as structured, versioned records on DeDi. Each key record contains the actual key material (PEM-encoded), metadata (algorithm, purpose, validity period), and a cryptographic proof anchored on-chain. Consumers discover and retrieve keys via a single API call. ### [](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi#how-it-works) How It Works Publish Organization publishes its public key(s) to a DeDi namespace. Each key is a record with PEM material, algorithm identifier, purpose tag, and validity dates. Rotate When a key is rotated, the organization publishes a new version. The old version remains on-chain with its proof β€” verifiers processing historical data can still resolve the key that was active at any point in time. Discover Any system calls the DeDi Lookup API with the key’s record ID. Response: JSON with the PEM key, metadata, version history, and on-chain proof. Sub-200ms. Verify The consumer verifies the cryptographic proof to confirm the key is authentic and unaltered. No need to contact the publisher. ### [](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi#what-changes) What Changes Before DeDi After DeDi Static .cer/.pem files on a website Structured, versioned records with actual key material Manual download, no change notification Key rotation propagates instantly via API Stale keys cached indefinitely Version history on-chain; current key always resolvable No way to verify key authenticity without contacting publisher Cryptographic proof verifiable by anyone, independently [PreviousRepresentative Use Cases](https://docs.nfh.global/dedi/resources/representative-use-cases) [NextAuthorized Entity Registry on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi) Last updated 1 month ago Was this helpful? * [The Problem](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi#the-problem) * [The DeDi Solution](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi#the-dedi-solution) * [How It Works](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi#how-it-works) * [What Changes](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi#what-changes) Was this helpful? --- # OpenAPI Specification | DeDi | NFH Fabric The DeDi.global OpenAPI specification provides a comprehensive, machine-readable description of our entire API surface. This specification follows OpenAPI 3.0 standards and enables automated tooling, code generation, and integration workflows. [Download OpenAPI specification](https://github.com/nfh-trust-labs/docs/blob/main/openAPI.yaml) ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#usage-scenarios) Usage Scenarios #### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#code-generation) Code Generation Generate client SDKs in multiple programming languages: GitBook AssistantAskCopy # Generate Python client openapi-generator-cli generate -i openAPI.yaml -g python -o ./dedi-python-client # Generate JavaScript client openapi-generator-cli generate -i openAPI.yaml -g javascript -o ./dedi-js-client # Generate Java client openapi-generator-cli generate -i openAPI.yaml -g java -o ./dedi-java-client #### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#api-documentation) API Documentation Generate interactive documentation: GitBook AssistantAskCopy # Swagger UI swagger-ui-serve openAPI.yaml # Redoc redoc-cli serve openAPI.yaml #### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#api-testing) API Testing Test with tools like Postman, Insomnia, Newman, or Dredd. ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#openapi-3.0-specification) OpenAPI 3.0 Specification The spec covers all endpoints, reusable schemas, authentication (Bearer token & cookie), response examples, and error codes. Core sections include security definitions, path operations, and component schemas. ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#integration-tools) Integration Tools * **Code Generation:** OpenAPI Generator, Swagger Codegen, AutoRest * **Documentation:** Swagger UI, Redoc, Stoplight * **Testing & Validation:** Spectral, Prism, Dredd ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#best-practices) Best Practices * Pin generator versions and review generated code * Customize documentation with interactive examples and error scenarios * Maintain backwards compatibility, use semantic versioning, and document changes ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#specification-contents) Specification Contents * **Authentication:** Login/logout, API key management, token refresh * **Core Resources:** Namespace, Registry, and Record CRUD * **Advanced:** Domain verification, bulk import/export, webhooks, delegation * **Administrative:** State management, version history, analytics ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#getting-started) Getting Started 1. Download the specification 2. Choose your tooling 3. Generate client code or documentation 4. Validate against the spec during development ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#related-resources) Related Resources * [Postman Collection](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection) : Interactive API testing * [API Reference Documentation](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis) : Human-readable docs * [Developer Guide](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation) : Integration best practices * [Authentication Guide](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access) : Security implementation [PreviousPostman Collection](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection) [NextFAQs](https://docs.nfh.global/dedi/miscellaneous/faqs) Last updated 1 month ago Was this helpful? * [Usage Scenarios](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#usage-scenarios) * [OpenAPI 3.0 Specification](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#openapi-3.0-specification) * [Integration Tools](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#integration-tools) * [Best Practices](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#best-practices) * [Specification Contents](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#specification-contents) * [Getting Started](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#getting-started) * [Related Resources](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification#related-resources) Was this helpful? --- # Creating and publishing Rego policy artifacts | Beckn Networks | NFH Fabric This guide explains how Network Facilitating Organizations (NFOs) can author policies in Rego, package them as OPA bundles, or a single rego file, publish them, and refer them in DeDi so that they can be discovered and evaluated for a specific network\_id. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-1.-overview) 1\. Overview Policies in the network are distributed as OPA bundles or a single rego file. Each bundle: * contains one or more Rego policy modules * may include policy data * exposes a decision rule that returns a validation result * is signed to ensure integrity * should be referenced in the network manifest by the NFO For a given network\_id, all applicable policy bundles are fetched and evaluated together. A request is considered valid only if all applicable policies return valid=true. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-2.-create-rego-policies-and-decision-rule) 2\. Create Rego Policies and Decision Rule Policies must be written in Rego and must expose a decision rule that returns the evaluation result. Every policy bundle (or the rego file in case of a single rego file) must define a rule that returns: GitBook AssistantAskCopy { "valid": true | false, "violations": ["string"] } #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#field-descriptions) Field descriptions Field Description valid Indicates whether the input satisfies the policy rules violations List of violations detected during evaluation #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#example-policy) Example policy The following example ensures that message.order.items.quantity.count is greater than zero. package retail.policy #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#example-query-path) Example query path The rule path must be recorded in the registry: data.retail.policy.result This value must be configured as policy\_query\_path. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-3.-organize-the-policy-repository) 3\. Organize the Policy Repository OPA does not require a fixed repository layout. Example repository: #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#bundle-files) Bundle files File Purpose .rego Policy logic data.json Optional structured data .manifest Bundle metadata The .manifest file is automatically created when building bundles. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-4.-build-and-sign-the-opa-bundle-or-rego-file) 4\. Build and Sign the OPA Bundle or Rego File To sign a single rego file please follow the instructions [here](https://docs.google.com/document/d/19BqwuHGUi3iHuQ-RiabBujxasOjNpZUmG3orPzkvq48/edit?tab=t.9ralphbrtk2p) . To sign an OPA bundle, download the OPA CLI from: [https://www.openpolicyagent.org/docs#1-download-opa](https://www.openpolicyagent.org/docs#1-download-opa) Once installed, build and sign a bundle: This command: * packages policy modules and data * generates a .manifest * signs the bundle * creates .signatures.json inside the bundle Reference: [https://www.openpolicyagent.org/docs/management-bundles](https://www.openpolicyagent.org/docs/management-bundles) You can use openssl to generate an ECDSA P-256 keypair compatible with `ES256` for signing your bundle: ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-5.-testing-policies-before-publishing) 5\. Testing Policies Before Publishing Before publishing bundles, authors must test the policies. This ensures that: * bundles load correctly * there are no namespace conflicts * policies produce the expected results when evaluated together #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#step-1-build-the-policy-bundle-if-using-bundles) Step 1 - Build the policy bundle (if using bundles) Build the bundles you intend to publish: Step 2 - Create sample input Example input: Save as input.json. #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#step-3-evaluate-the-policy) Step 3 - Evaluate the policy Use the OPA CLI to load the built bundle or the single rego file and evaluate the decision rules. In case of a bundle: In case of a single file: Example output: Testing bundles ensures that policies execute correctly before publishing them. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-6.-publish-the-policy) 6\. Publish the Policy The policy must be published to a stable URL. Example: https://github.com/nfo/policies/releases/download/v1/retail-bundle.tar.gz Recommended hosting options: * GitHub Releases * Object storage * CDN Immutable URLs are recommended. lightbulb **Testing directly without setting up network manifest**: You can directly test the policy by configuring the [OPA Policy Checker plugin](https://github.com/beckn/beckn-onix/tree/main/pkg/plugin/implementation/opapolicychecker) in Beckn ONIX. For testing you can use `type: bundle` pointing to a local signed OPA bundle. Add it to your adapter's `networkPolicyConfig` YAML under your network\_id or a `default` key so it applies to all requests regardless of `network_id`: You can refer to _Step 8_ in this guide to see how to publish your public key. Then reference it from your adapter config. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-7.-create-or-update-your-manifest-file-to-point-to-the-bundle) 7\. Create or Update your manifest file to point to the bundle ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-8.-ensure-the-registry-metadata-for-the-network-references-the-manifest-file-and-the-public-key-is-p) 8\. Ensure the registry metadata for the network references the manifest file and the public key is published #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#publishing-signing-public-key) Publishing signing public key Login to [DeDi.Global](https://publish.dedi.global/) . In your namespace, you can create a public key registry to publish your public key. Click on the new registry button and select the Public Key schema. When publishing the public key in DeDi for bundles signed with `ES256`, use: * `keyType`: `ECDSA` * `keyFormat`: `base64` * `publicKey`: the Base64-encoded contents of the public key (excluding the `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----` lines), copied into the corresponding field in DeDi Once the record is published and it's status is live, you can go to the record to copy its lookup URL from the widget on the page. #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#referencing-the-network-manifest) Referencing the network manifest Go to the NFO reference registry where the reference to NP registries are added in DeDi Global. Once you have located the registry click on the 3 dots on the card: ![](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2F3638162302-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMnBHMPqabDZYD3t20Ocv%252Fuploads%252Fgit-blob-f2e12e3e32b0158f81af31bb39a6ced5043afcb7%252Funknown.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=758f66a4&sv=2) Click on update. ![](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2F3638162302-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMnBHMPqabDZYD3t20Ocv%252Fuploads%252Fgit-blob-5eff4c1a9db754d8c904440c9529e04ad8509a99%252Funknown%2520%281%29.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=6f89dace&sv=2) Ensure the following fields are present as metadata for the registry: ![](https://docs.nfh.global/~gitbook/image?url=https%3A%2F%2F3638162302-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FMnBHMPqabDZYD3t20Ocv%252Fuploads%252Fgit-blob-4842bf398606ba9aa8fe6b0a3dc1dadc37c0a8aa%252Funknown%2520%282%29.png%3Falt%3Dmedia&width=768&dpr=3&quality=100&sign=83c97675&sv=2) Field Name Description manifest\_url The URL pointing to the network's policy manifest file. signing\_public\_key\_lookup\_url The lookup URL of the public key published in DeDi. manifest\_signature\_url The URL pointing to the signature of the network manifest file. lightbulb **Referencing the policy using network ID in beckn ONIX**: To resolve policies automatically from a verified network manifest set for a network in the [OPA Policy Checker plugin](https://github.com/beckn/beckn-onix/tree/main/pkg/plugin/implementation/opapolicychecker) , set `type: manifest` for the network entry in your `networkPolicyConfig` file, using the `network_id` as the key. Also configure the `manifestLoader` plugin in the same handler β€” the OPA plugin uses it to fetch and verify the manifest at startup: The policy source, query path, and signing details are all read from the manifest β€” no `location`, `query`, or `verification` block is needed in the config. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-9.-updating-policies) 9\. Updating Policies There are two ways to update policies. #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#option-1-publish-a-new-version) Option 1 β€” Publish a new version 1. Update the policy files 2. Build a new bundle 3. Update the manifest file #### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#option-2-update-the-bundle-at-the-same-url) Option 2 β€” Update the bundle at the same URL Policies can also be updated at the same static URL. It is recommended to update the release number in the network manifest when you do so. Example: When the bundle content changes: * the updated bundle will be fetched automatically * the updated policies will be applied * no restart is required If using a mutable URL, ensure the path remains stable. ### [](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-10.-best-practices) 10\. Best Practices * Always sign policy bundles or files * Prefer immutable artifact URLs * Use clear package naming * Version policies explicitly * Test all policies for the same network\_id together before publishing [PreviousCreating and publishing the network manifest](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-the-network-manifest) [NextSigning a single file](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/signing-a-single-file) Last updated 1 month ago Was this helpful? * [1\. Overview](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-1.-overview) * [2\. Create Rego Policies and Decision Rule](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-2.-create-rego-policies-and-decision-rule) * [3\. Organize the Policy Repository](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-3.-organize-the-policy-repository) * [4\. Build and Sign the OPA Bundle or Rego File](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-4.-build-and-sign-the-opa-bundle-or-rego-file) * [5\. Testing Policies Before Publishing](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-5.-testing-policies-before-publishing) * [6\. Publish the Policy](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-6.-publish-the-policy) * [7\. Create or Update your manifest file to point to the bundle](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-7.-create-or-update-your-manifest-file-to-point-to-the-bundle) * [8\. Ensure the registry metadata for the network references the manifest file and the public key is published](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-8.-ensure-the-registry-metadata-for-the-network-references-the-manifest-file-and-the-public-key-is-p) * [9\. Updating Policies](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-9.-updating-policies) * [10\. Best Practices](https://docs.nfh.global/beckn/creating-an-open-network/configuring-network-policies/creating-and-publishing-rego-policy-artifacts#id-10.-best-practices) Was this helpful? GitBook AssistantAskCopy default result := { "valid": true, "violations": [] } result := { "valid": count(violations) == 0, "violations": violations } violations contains msg if { some item in input.message.order.items item.quantity.count <= 0 msg := "message.order.items.quantity.count must be greater than 0" } GitBook AssistantAskCopy repo/ retail-policy/ validation.rego pricing_rules.rego data.json prod-policy/ prod_validation.rego GitBook AssistantAskCopy opa build \ --bundle retail-policy/ \ --signing-key private.pem \ --signing-alg ES256 \ -o retail-bundle.tar.gz GitBook AssistantAskCopy # GENERATE PRIVATE KEY openssl ecparam -name prime256v1 -genkey -noout -out private.pem # GENERATE PUBLIC KEY openssl pkey -in private.pem -pubout -out public.pem # Keys will be saved as private.pem and public.pem GitBook AssistantAskCopy opa build \ --bundle retail-policy/ \ --signing-key private.pem \ --signing-alg ES256 \ -o retail-bundle.tar.gz GitBook AssistantAskCopy { "message": { "order": { "items": [\ {\ "id": "item1",\ "quantity": {\ "count": 0\ }\ },\ {\ "id": "item2",\ "quantity": {\ "count": 2\ }\ }\ ] } } } GitBook AssistantAskCopy opa eval \ -b retail-bundle.tar.gz \ -i input.json \ --format=raw \ data.retail.validation.result GitBook AssistantAskCopy opa eval \ -d policy.rego \ -i input.json \ --format=raw \ data.retail.validation.result GitBook AssistantAskCopy { "valid": false, "violations": [\ "message.order.items.quantity.count must be greater than 0"\ ] } GitBook AssistantAskCopy # config/opa-network-policies.yaml networkPolicies: nfo.com/production: type: bundle location: https://github.com/nfo/policies/releases/download/v1/retail-bundle.tar.gz query: "data.retail.policy.result" verification: enabled: true publicKeyLookupUrl: https://api.dedi.global/dedi/lookup/your-nfo.example.com/public_key_test/your-key-name GitBook AssistantAskCopy checkPolicy: id: opapolicychecker config: networkPolicyConfig: ./config/opa-network-policies.yaml # Also add checkPolicy to the handler's steps list. GitBook AssistantAskCopy manifest_version: "1.0" manifest_type: "network-manifest" network_id: "nfo.com/production" publisher: role: "NFO" domain: "nfo.example.org" policies: type: "rego" source: "bundle" bundle: id: "network-policy-bundle" url: "https://github.com/nfo/policies/releases/download/v1/retail-bundle.tar.gz" policy_query_path: "data.retail.policy.result" observability: enabled: true config: url: "https://nfo.example.org/observ/fields.yaml" signature_url: "https://nfo.example.org/observ/fields.yaml.sig" collector: url: "https://telemetry.nfo.example.org/v1/network/events" governance: effective_from: "2026-03-10T00:00:00Z" effective_until: "2027-03-10T00:00:00Z" signed: true signature_url: "https://nfo.example.org/network-runtime-manifest.sig" GitBook AssistantAskCopy # config/opa-network-policies.yaml networkPolicies: nfo.com/production: type: manifest GitBook AssistantAskCopy manifestLoader: id: manifestloader config: cacheTTL: 24h checkPolicy: id: opapolicychecker config: networkPolicyConfig: ./config/opa-network-policies.yaml GitBook AssistantAskCopy https://github.com/nfo/policies/releases/download/latest/retail-bundle.tar.gz --- # DeDi.global | DeDi | NFH Fabric [](https://docs.nfh.global/dedi/resources/dedi.global#the-problem) The Problem ----------------------------------------------------------------------------------- Every day, millions of digital transactions depend on trust artifacts that live in the wrong formats: PDF lists of authorized entities, CSV downloads of public keys, web pages with schema definitions. Verifying these artifacts is slow, manual, and error-prone. There is no universal way to ask: β€œIs this information current, authentic, and unaltered?” [](https://docs.nfh.global/dedi/resources/dedi.global#the-solution) The Solution ------------------------------------------------------------------------------------- DeDi.global transforms static public registries into machine-readable, cryptographically verifiable, tamper-proof directories accessible via a single API. It is operated by Networks for Humanity Foundation as free, public good infrastructure. DeDi.global is built on the Decentralized Directory Protocol (DDP) β€” an open standard under Linux Foundation Decentralized Trust (LFDT). The protocol is not a software product. It is a universal, interoperable foundation for accessing and verifying public information. Anyone can implement it. [](https://docs.nfh.global/dedi/resources/dedi.global#architecture) Architecture ------------------------------------------------------------------------------------- DeDi organizes information into three tightly coupled tiers: 1 #### [](https://docs.nfh.global/dedi/resources/dedi.global#namespace) Namespace The root trust anchor. Corresponds to an organization and its verified domain name. All API calls begin with the namespace. Domain verification via DNS TXT records makes URLs human-readable (e.g., /dedi/dhiway.com/employees/Alice) and establishes organizational provenance. 2 #### [](https://docs.nfh.global/dedi/resources/dedi.global#registry) Registry A directory of records within a namespace. Each registry has a configurable schema that defines the structure and types of its entries. 3 #### [](https://docs.nfh.global/dedi/resources/dedi.global#record) Record An individual data entry β€” the actual value or pointer to information. Each record is independently versioned and cryptographically anchored. [](https://docs.nfh.global/dedi/resources/dedi.global#two-core-protocol-endpoints) Two Core Protocol Endpoints ------------------------------------------------------------------------------------------------------------------- Lookup and Query are the protocol foundation. DeDi also exposes endpoints for version history, advanced search, cryptographic verification, subscriptions, and state management. **Lookup** Retrieve a specific namespace, registry, or record by identifier. Returns the entry with its cryptographic proof. Supports version-specific and historical (as\_on) lookups. Look up a public encryption key by record ID β†’ get key material + on-chain proof **Query** Search a namespace or registry by field values, status, date range, or name. Returns matching entries with proofs. Supports pagination, sorting, and historical queries. Query all active authorized entities β†’ get list with entity codes, authorization status, and proofs Responses are JSON, sub-200ms, and include cryptographic proof that the entry is authentic, unaltered, and anchored on-chain. [PreviousHow to Use DeDi](https://docs.nfh.global/dedi/resources/the-vision-for-decentralised-directory-dedi/how-to-use-dedi) [NextFeatures of DeDi.global](https://docs.nfh.global/dedi/resources/dedi.global/features-of-dedi.global) Last updated 1 month ago Was this helpful? * [The Problem](https://docs.nfh.global/dedi/resources/dedi.global#the-problem) * [The Solution](https://docs.nfh.global/dedi/resources/dedi.global#the-solution) * [Architecture](https://docs.nfh.global/dedi/resources/dedi.global#architecture) * [Two Core Protocol Endpoints](https://docs.nfh.global/dedi/resources/dedi.global#two-core-protocol-endpoints) Was this helpful? --- # Authorized Entity Registry on DeDi | DeDi | NFH Fabric [](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi#the-problem) The Problem ----------------------------------------------------------------------------------------------------------------------------------- Most ecosystems maintain lists of authorized entities β€” service agencies, authentication providers, KYC operators, certified vendors. These lists are typically published as periodic PDFs or static web pages. The problem: when an entity’s authorization is revoked, the change only appears in the next PDF release. Between updates, revoked entities can continue operating because consuming systems have no real-time signal. [](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi#the-dedi-solution) The DeDi Solution ----------------------------------------------------------------------------------------------------------------------------------------------- Publish authorized entity lists as queryable, real-time registries on DeDi. Each entity record contains: entity name, entity code, authorization type, status (active/suspended/revoked), authorization date, and any relevant metadata. Changes propagate instantly. ### [](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi#how-it-works) How It Works Publish Ecosystem operator publishes the authorized entity list to a DeDi namespace. Each entity is a record with structured fields. Query Any party queries the registry by entity code, status, or authorization type. Returns matching records with proofs. Update in real-time When an entity’s status changes (suspended, revoked, reinstated), the operator updates the record. The change is on-chain within seconds. Audit trail Every status change is versioned and anchored. Regulators can verify the exact authorization state at any historical point in time. Example API Calls GitBook AssistantAskCopy Look up a specific entity: GET /dedi/lookup/{namespace}/{registry}/{entity-code} Query all active entities: GET /dedi/query/{namespace}/{registry}?status=active [](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi#what-changes) What Changes ------------------------------------------------------------------------------------------------------------------------------------- Periodic PDF lists, updated monthly or quarterly Real-time queryable registry, changes propagate in seconds Revoked entities invisible until next PDF release Revocations visible immediately via API Manual verification β€” search a PDF, hope it’s current Programmatic verification β€” one API call, with proof No audit trail for authorization changes Full version history, on-chain, independently verifiable [PreviousPublic Key Registry on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/public-key-registry-on-dedi) [NextRevocation Registry on DeDi](https://docs.nfh.global/dedi/resources/representative-use-cases/revocation-registry-on-dedi) Last updated 1 month ago Was this helpful? * [The Problem](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi#the-problem) * [The DeDi Solution](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi#the-dedi-solution) * [How It Works](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi#how-it-works) * [What Changes](https://docs.nfh.global/dedi/resources/representative-use-cases/authorized-entity-registry-on-dedi#what-changes) Was this helpful? --- # API Tools & Resources | DeDi | NFH Fabric This section provides essential tools and resources for developers working with the DeDi.global API. [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#overview) Overview ----------------------------------------------------------------------------------------- To help you get started quickly and efficiently with DeDi.global APIs, we provide comprehensive toolsets including: * **Postman Collection**: Ready-to-use API requests for testing and development * **OpenAPI Specification**: Complete API documentation in machine-readable format [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#quick-access) Quick Access ------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#postman-collection) πŸš€ [Postman Collection](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection) Import our complete Postman collection to start making API requests immediately. Includes pre-configured environments, authentication, and example requests for all endpoints. ### [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#openapi-specification) πŸ“‹ [OpenAPI Specification](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification) Access the complete OpenAPI 3.0 specification for automated tooling, code generation, and comprehensive API documentation. [](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#getting-started) Getting Started ------------------------------------------------------------------------------------------------------- 1. **For Interactive Testing**: Start with our [Postman Collection](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection) 2. **For Code Generation**: Use our [OpenAPI Specification](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/openapi-specification) 3. **For Production Integration**: Refer to our [API Reference](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis) These tools complement our comprehensive [Developer Documentation](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation) and provide practical resources for seamless API integration. [PreviousWatch Feature](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature) [NextPostman Collection](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools/postman-collection) Last updated 1 month ago Was this helpful? * [Overview](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#overview) * [Quick Access](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#quick-access) * [πŸš€ Postman Collection](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#postman-collection) * [πŸ“‹ OpenAPI Specification](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#openapi-specification) * [Getting Started](https://docs.nfh.global/dedi/api-tools-and-resources/api-tools#getting-started) Was this helpful? --- # Bulk Upload | DeDi | NFH Fabric DeDi Global supports CSV-based bulk uploads for efficient data import into your registries. ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#via-user-interface) Via User Interface 1. Go to your namespace (or create one) and select **Bulk Upload** 2. Upload a CSV file: * First row: Column headers (must match your schema properties) * Remaining rows: Records to import 3. For existing registries: navigate to your registry, select Bulk Upload, and ensure your CSV columns match the registry schema. ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#via-api) Via API GitBook AssistantAskCopy POST /dedi/bulk-upload Content-Type: multipart/form-data Field Value `namespace` Your namespace ID or verified domain name `file` CSV file **Example:** GitBook AssistantAskCopy curl -X POST https://api.dedi.global/dedi/bulk-upload \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "namespace=your-domain.com" \ -F "[emailΒ protected]" > **Tip:** After domain verification, you can use your domain name (e.g., `your-domain.com`) instead of the raw namespace ID. ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#csv-format) CSV Format #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#sample-csv-public-key-registry) Sample CSV β€” Public Key Registry #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#sample-csv-membership-registry) Sample CSV β€” Membership Registry #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#requirements) Requirements * First row must contain column headers * Headers must match your schema property names exactly * Values must conform to the property types defined in your schema * Schema consistency is required β€” mismatched schemas will fail the upload [PreviousSchema design](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design) [NextDelegation Guide](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide) Last updated 1 month ago Was this helpful? * [Via User Interface](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#via-user-interface) * [Via API](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#via-api) * [CSV Format](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload#csv-format) Was this helpful? GitBook AssistantAskCopy keyId,algorithm,publicKeyPem,purpose,validFrom key-001,Ed25519,MCowBQYDK2VwAyEA...,signing,2025-01-01T00:00:00Z key-002,ECDSA-P256,MFkwEwYHKoZIzj0C...,encryption,2025-03-15T00:00:00Z key-003,Ed25519,MCowBQYDK2VwAyEA...,authentication,2025-06-01T00:00:00Z GitBook AssistantAskCopy memberId,name,role,status,joinedDate M001,Acme Corp,full_member,active,2024-01-15 M002,Beta Industries,associate,active,2024-03-20 M003,Gamma Ltd,full_member,inactive,2024-06-01 --- # State management | DeDi | NFH Fabric DeDi.global uses a compact lifecycle model for namespaces, registries, and records. [](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management#supported-states) Supported states ---------------------------------------------------------------------------------------------------------------------- Entity States Namespace `live` Registry `live`, `inactive` Record `draft`, `live` [](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management#how-the-lifecycle-works) How the lifecycle works ------------------------------------------------------------------------------------------------------------------------------------ * A namespace remains `live` until it is deleted. * A registry can move between `live` and `inactive`. * A record starts as `draft` and becomes `live` when published. * Updating a live record creates a new live version. * Deletion removes the entity from active access surfaces and moves it into the recovery surface. [](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management#delete-and-restore) Delete and restore -------------------------------------------------------------------------------------------------------------------------- * Use the deletion APIs to remove namespaces, registries, or records. * Use the deleted-entity listing APIs to discover recoverable items. * Use the restore APIs to recover deleted data within the retention window. * The current implementation keeps deleted entities restorable for a configurable retention period with a default of `3` days. [](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management#related-references) Related references -------------------------------------------------------------------------------------------------------------------------- * API reference: [State Management APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management) * Publish and draft workflows: [Publish APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish) * Versioned updates: [Update APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update) [PreviousDelegation Guide](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide) [NextWatch Feature](https://docs.nfh.global/dedi/dedi.global-developers/guides/watch-feature) Last updated 1 month ago Was this helpful? * [Supported states](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management#supported-states) * [How the lifecycle works](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management#how-the-lifecycle-works) * [Delete and restore](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management#delete-and-restore) * [Related references](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management#related-references) Was this helpful? --- # Schema design | DeDi | NFH Fabric Each registry in DeDi defines a schema β€” the structure of the records it contains. When creating a registry, you provide a schema. There are two options: #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design#option-1-use-a-pre-defined-schema-tag) **Option 1: Use a pre-defined schema tag.** Each tag points to a JSON Schema stored in the system. To list available tags: GitBook AssistantAskCopy GET /dedi/lookup/dedi.global/Schemas Available templates include: Membership, Public Key, Revocation, Beckn. #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design#option-2-provide-a-custom-json-schema) **Option 2: Provide a custom JSON Schema.** JSON Schema Draft 7 is supported. #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design#example-minimal-custom-schema) Example: Minimal Custom Schema GitBook AssistantAskCopy { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Example record", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] } #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design#example-public-key-registry-schema) Example: Public Key Registry Schema ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design#bulk-upload-and-schemas) Bulk Upload and Schemas If you are doing a bulk upload, the importer uses the first row of the CSV to map columns to schema properties. See the [Bulk Upload guide](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload) for details. ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design#see-also) See Also * [Lookup API](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access) β€” Query available schema tags * [Bulk Upload guide](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload) β€” CSV import with schema mapping [PreviousGuides](https://docs.nfh.global/dedi/dedi.global-developers/guides) [NextBulk Upload](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload) Last updated 1 month ago Was this helpful? * [Bulk Upload and Schemas](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design#bulk-upload-and-schemas) * [See Also](https://docs.nfh.global/dedi/dedi.global-developers/guides/schema-design#see-also) Was this helpful? GitBook AssistantAskCopy { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Public Key Record", "type": "object", "properties": { "keyId": { "type": "string", "description": "Unique key identifier" }, "algorithm": { "type": "string", "enum": ["Ed25519", "ECDSA-P256", "RSA-2048"] }, "publicKeyPem": { "type": "string", "description": "PEM-encoded public key" }, "purpose": { "type": "string", "enum": ["signing", "encryption", "authentication"] }, "validFrom": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time" } }, "required": ["keyId", "algorithm", "publicKeyPem", "purpose", "validFrom"] } --- # Catalog Concepts | Beckn Networks | NFH Fabric This page builds your mental model of what you are publishing to CATALG. It walks through the catalog object, its parts, and the rules that govern how CATALG processes it. > If you have not yet published a catalog, run the [Quickstart](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/quickstart) > first β€” it will make every concept here much more concrete. > Looking for exact field shapes, endpoint paths, and error codes? See the [API Reference](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/api-reference) > . * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#a-catalog-at-a-glance) A catalog at a glance ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ A **catalog** is the top-level payload you publish. It carries the identity of the publishing provider, the resources they offer, and any pricing or commercial terms attached to those resources. Here is a complete catalog stripped to its essentials: GitBook AssistantAskCopy { "id": "CAT-FRESHMART-2026", "descriptor": { "name": "FreshMart Daily Catalog", "shortDesc": "Fresh groceries β€” Bangalore South" }, "provider": { "id": "freshmart-blr-001", "descriptor": { "name": "FreshMart Koramangala" } }, "resources": [ ... ], "offers": [ ... ] } A catalog must contain at least one of `resources` or `offers` β€” both is common. How the catalog is _processed_ (its type, how updates are applied, who can see it) is declared **separately** in `publishDirectives` at the message level, not inside the catalog object itself. The sections below cover each piece in turn. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#resources) Resources ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ A **resource** is a domain-neutral unit of value. It can be a product SKU on a grocery shelf, an EV charging slot, a clinic appointment, a carbon credit, a job role β€” anything a network wants to make discoverable. The core fields (`id`, `descriptor`) are universal. Domain-specific properties live inside `resourceAttributes`, declared using a JSON-LD `@context` and `@type`. This pattern lets any domain extend the schema without modifying the core Beckn protocol. The `@context` URI tells consumers which schema vocabulary applies. CATALG uses it during domain schema validation (see [Validation](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#validation) ). * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#offers) Offers ------------------------------------------------------------------------------------------------------------------------------------------------------------------ An **offer** captures the commercial terms under which one or more resources can be obtained β€” price, discount, eligibility, validity. Offers are _separate from_ resources and are linked by `resourceIds`, which means the same resource can carry multiple competing offers from different providers. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#provider-level-offers) Provider-level offers An offer with **no** `**resourceIds**` applies to all resources published by that provider. Use this for blanket promotions, free-delivery thresholds, loyalty programmes, or any commercial term not tied to a specific resource. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#offer-only-catalogs) Offer-only catalogs A catalog can contain offers without any resources of its own. This is how a provider publishes pricing overlays or promotions that reference resources published _by another provider_. The catalog must still carry `id`, `descriptor`, and `provider` β€” only `resources` is omitted. > **Discoverability:** Offer-only catalogs and provider-level offers are not independently discoverable via resource search. A Discovery Service resolves and attaches these offers to matching real resources at query time. If no matching real resources exist in the Discovery Service, the offers will not appear in search results. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#provider) Provider ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `provider` block identifies who is publishing the catalog and where they operate. The `availableAt` array carries geo-coordinates and address, enabling spatial search on Discovery Services. Field Required Description `id` yes Stable provider identifier within the publisher's namespace `descriptor` yes `name`, optional `shortDesc`, `longDesc`, `thumbnailImage` `availableAt` no Array of `Location` objects β€” `geo` (GeoJSON Point) + `address` (structured postal address). Resources inherit provider locations; there is no per-resource location field `rating` no Aggregate rating across the provider's resources * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#catalog-types) Catalog types -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Every catalog is one of two types, declared via `catalogType` in `publishDirectives`. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#regular) REGULAR A commercial catalog published by a **Provider Node**. Resources represent what the provider is currently offering. REGULAR catalogs can contain resources, offers, or both. Most catalogs on a network are REGULAR. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#master-template) MASTER (template) A **master catalog** is a network-wide template published by a **network facilitator or domain authority**. It defines the canonical specification for a class of product or service β€” authoritative name, brand identity, schema type, unit of measure, and any other attributes the network wants to standardise across all providers. **Why templates exist.** Without templates, every provider on a network independently defines the same product β€” different naming conventions, inconsistent schema types, missing attributes, conflicting brand spellings. A master resource establishes one authoritative definition that all providers on the network build from. When a consumer searches for "India Gate Basmati Rice 1KG", every store's listing refers back to the same canonical resource β€” ensuring consistent data across the entire network. > Master catalogs **do not contain offers**. They are pure resource definitions. Pricing, promotions, and commercial terms belong in REGULAR catalogs. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#extending-a-master-in-a-regular-catalog) Extending a master in a REGULAR catalog A Provider Node extends a master resource using `resourceDirectives` inside `publishDirectives`. The provider supplies only the fields unique to their offering β€” local pricing, stock status, location β€” and inherits everything else from the template. **Template attributes are immutable.** The provider can _add_ new fields but cannot change values defined by the template. This is what guarantees consumers see consistent, authoritative data β€” canonical brand name, schema type, fixed specifications β€” regardless of which provider's catalog they are looking at. For the full schema of `publishDirectives` and `resourceDirectives`, see [API Reference β†’ catalog/publish](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/api-reference#catalogpublish) . * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#publish-directives) Publish directives ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ `publishDirectives` is an array carried at the **message** level (not inside the catalog) that controls how CATALG processes each catalog. Every entry is matched to a catalog by `catalogId`. `publishDirectives` itself is optional. When it is omitted entirely, CATALG processes every catalog in the request with its own defaults. The moment you include a `publishDirectives` entry, `catalogType` becomes mandatory within that entry; `updateMode` falls back to its default of `MERGE` if not specified. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#update-modes) Update modes `updateMode` controls how CATALG processes incoming resources for a given `catalogId`: * **MERGE** _(default)_ β€” Adds or updates incoming resources. Resources already published for this catalog but not in the incoming set are preserved. Use this for incremental updates: publish only what has changed. * **FULL** β€” Replaces the entire resource set for this `catalogId`. All previously published resources are removed first, then the incoming set is inserted. Use this for complete replacements: retiring old SKUs, major restructure. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#visibility-visibleto) Visibility β€” `visibleTo` `visibleTo` restricts distribution of a catalog to a specific list of **registry-registered network IDs**. The catalog is delivered only to Discovery Services that subscribe to one of those networks. **When omitted** β€” or when `publishDirectives` itself is not provided β€” the catalog is distributed via the **default global network** `**nfh.global/beckn-nodes**`. Every Discovery Service subscribed to that network receives the catalog. This is the catch-all path: it lets a Provider Node publish without explicit visibility configuration and have the catalog broadly discoverable across the Beckn fabric. When `visibleTo` is set, CATALG enforces it at delivery time β€” a Discovery Service whose subscription does not cover any of the listed networks will not receive this catalog via `catalog/push`, even if it is subscribed to the default global network. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#ownership) Ownership ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ CATALG identifies the caller from the Beckn HTTP Signature in the `Authorization` header on every request. Ownership rules are uniform across endpoints: the identity that originally created a resource is the only identity that can later modify it. **Catalog ownership.** A catalog belongs to the identity that originally published it. Only that same identity can submit updates or replacements to an existing `catalogId`. A request from any other identity is rejected. This applies at the resource level too β€” every resource in a catalog is owned by the publisher of that catalog. **Subscription ownership.** A subscription belongs to the identity that created it. Only that same identity may list, view, update, or deactivate the subscription. Calls from any other identity return `403 NackForbidden`. **Template resource integrity.** Master resources are published and maintained by the network facilitator. Any Provider Node can extend a template and add new fields, but the template's defined values are inherited as-is and cannot be changed by a provider. * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#validation) Validation -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Every catalog passes through a layered set of checks before it is accepted. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#authorization) Authorization The request must carry a valid **Beckn HTTP Signature** in the `Authorization` header. CATALG resolves the public key from the DeDi registry using the `subscriberId` and `recordId` from the `keyId`, and verifies the signature. Missing, expired, or unrecognised signatures are rejected immediately. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#core-protocol-schema) Core protocol schema CATALG validates that the request structure conforms to the **Beckn v2.0 protocol schema** β€” required context fields, correct action value, correct field names (`resources`, not `items`; `resourceAttributes`, not `itemAttributes`), and the structure of `publishDirectives`. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#domain-schema) Domain schema CATALG validates that each resource's `resourceAttributes`, each offer's `offerAttributes`, and each consideration's `considerationAttributes` conform to the **domain schema** declared in their `@context` URI β€” for example, that resources claiming `@type: RetailResource` actually carry the attributes the retail schema requires. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#ownership-check) Ownership check For updates to an existing `catalogId`, the caller's identity β€” derived from the Beckn HTTP Signature in the `Authorization` header β€” must match the identity that originally published the catalog. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#what-fails-when) What fails when Failure When you find out Authorization, core schema, or ownership **Synchronous rejection** β€” HTTP 400 / 401 / 403 before the catalog is accepted Domain schema **Asynchronous** β€” per-catalog `REJECTED` or `PARTIAL` result delivered via `POST /catalog/on_publish` * * * [](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#processing-results) Processing results ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ After processing, CATALG sends a `POST /catalog/on_publish` callback to the publisher's `bppUri` with one result per submitted catalog. Each result carries one of: Status Meaning `ACCEPTED` Catalog processed and distributed to all matching subscribers `REJECTED` Catalog rejected entirely β€” `errors` array explains what failed `PARTIAL` Some resources accepted, some rejected β€” see `errors` array For the exact callback payload shape, see [API Reference β†’ catalog/on\_publish](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/api-reference#catalogon_publish) . * * * **Next:** [Subscription & Distribution β†’](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution) [PreviousQuickstart](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/quickstart) [NextSubscription & Distribution](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/subscription-and-distribution) Last updated 9 days ago Was this helpful? * [A catalog at a glance](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#a-catalog-at-a-glance) * [Resources](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#resources) * [Offers](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#offers) * [Provider-level offers](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#provider-level-offers) * [Offer-only catalogs](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#offer-only-catalogs) * [Provider](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#provider) * [Catalog types](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#catalog-types) * [REGULAR](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#regular) * [MASTER (template)](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#master-template) * [Extending a master in a REGULAR catalog](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#extending-a-master-in-a-regular-catalog) * [Publish directives](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#publish-directives) * [Update modes](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#update-modes) * [Visibility β€” visibleTo](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#visibility-visibleto) * [Ownership](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#ownership) * [Validation](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#validation) * [Authorization](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#authorization) * [Core protocol schema](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#core-protocol-schema) * [Domain schema](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#domain-schema) * [Ownership check](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#ownership-check) * [What fails when](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#what-fails-when) * [Processing results](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/publish-catalogs-using-catalg/catalog-concepts#processing-results) Was this helpful? GitBook AssistantAskCopy { "id": "ITEM-BASMATI-RICE-1KG", "descriptor": { "name": "India Gate Basmati Rice", "shortDesc": "Aged basmati, 1 kg pack" }, "resourceAttributes": { "@context": "https://schema.beckn.io/RetailResource/2.1/context.jsonld", "@type": "RetailResource", "brand": "India Gate", "sku": "BSMTI-1KG-IG" } } GitBook AssistantAskCopy { "id": "OFFER-BASMATI-MAY26", "descriptor": { "name": "May Staples Deal" }, "resourceIds": ["ITEM-BASMATI-RICE-1KG"], "validity": { "startDate": "2026-05-01T00:00:00Z", "endDate": "2026-05-31T23:59:59Z" }, "offerAttributes": { "@context": "https://schema.beckn.io/RetailOffer/2.1/context.jsonld", "@type": "RetailOffer", "isActive": true }, "considerations": [\ {\ "id": "PRICE-BASMATI",\ "considerationAttributes": {\ "@context": "https://schema.beckn.io/PriceSpecification/2.0/context.jsonld",\ "@type": "PriceSpecification",\ "value": 95,\ "currency": "INR"\ }\ }\ ] } GitBook AssistantAskCopy { "id": "OFFER-FREE-DELIVERY", "descriptor": { "name": "Free delivery on orders above β‚Ή500" }, "offerAttributes": { "@context": "https://schema.beckn.io/RetailOffer/2.1/context.jsonld", "@type": "RetailOffer", "isActive": true }, "considerations": [\ {\ "id": "DELIVERY-WAIVER",\ "considerationAttributes": {\ "@context": "https://schema.beckn.io/PriceSpecification/2.0/context.jsonld",\ "@type": "PriceSpecification",\ "value": 0,\ "currency": "INR",\ "components": [\ { "type": "DELIVERY", "value": 0, "currency": "INR" }\ ]\ }\ }\ ] } GitBook AssistantAskCopy { "id": "freshmart-blr-001", "descriptor": { "name": "FreshMart Koramangala", "shortDesc": "Neighbourhood grocery, open 7am–10pm" }, "availableAt": [\ {\ "geo": { "type": "Point", "coordinates": [77.6278, 12.9352] },\ "address": {\ "streetAddress": "42 80-Feet Road, Koramangala 4th Block",\ "addressLocality": "Bengaluru",\ "addressRegion": "Karnataka",\ "postalCode": "560034",\ "addressCountry": "IN"\ }\ }\ ] } GitBook AssistantAskCopy "resourceDirectives": [\ {\ "resourceId": "MY-LOCAL-BASMATI",\ "extends": { "masterResourceId": "MASTER-INDIA-GATE-BASMATI-1KG" }\ }\ ] GitBook AssistantAskCopy "message": { "publishDirectives": [\ {\ "catalogId": "CAT-FRESHMART-2026",\ "catalogType": "REGULAR",\ "updateMode": "MERGE",\ "visibleTo": ["local-retail.net/grocery-net"]\ }\ ], "catalogs": [ { "id": "CAT-FRESHMART-2026", "...": "..." } ] } GitBook AssistantAskCopy "publishDirectives": [\ {\ "catalogId": "CAT-WHOLESALE-2026",\ "catalogType": "REGULAR",\ "visibleTo": ["acme.net/distributor-net", "acme.net/wholesale-net"]\ }\ ] --- # Delegation Guide | DeDi | NFH Fabric Delegation is a powerful feature that allows you to grant management permissions to other registered DeDi users. ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide#prerequisites) Prerequisites Before setting up delegation, ensure that: * You have a registered DeDi account with administrative access to the registry * The delegate (person you want to grant access to) has a registered DeDi Global account * You have the delegate's registered email address ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide#current-limitations) Current Limitations * Delegation is currently supported only at the **registry** level * Delegation permissions cannot be partially restricted (it's all or nothing) ### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide#setting-up-delegation) Setting Up Delegation You can set up delegation through either the UI or the API. #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide#using-the-ui) Using the UI 1. Navigate to your registry dashboard 2. Click on the three dots at the top right corner. 3. Click "Delegate" 4. Enter the delegate's email address 5. Confirm the addition #### [](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide#using-the-api) Using the API To add a delegate via API, use the following endpoint: **Request Body** **Response** A successful delegation will return a 200 OK response. [PreviousBulk Upload](https://docs.nfh.global/dedi/dedi.global-developers/guides/bulk-upload) [NextState management](https://docs.nfh.global/dedi/dedi.global-developers/guides/state-management) Last updated 1 month ago Was this helpful? * [Prerequisites](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide#prerequisites) * [Current Limitations](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide#current-limitations) * [Setting Up Delegation](https://docs.nfh.global/dedi/dedi.global-developers/guides/delegation-guide#setting-up-delegation) Was this helpful? GitBook AssistantAskCopy POST /dedi/{{namespace}}/{{registry_name}}/add-delegate GitBook AssistantAskCopy { "email": "[emailΒ protected]" } --- # Getting started with Beckn | Beckn Networks | NFH Fabric A hands-on starter kit for running a live beckn network in your own environment within **10 minutes** β€” complete with a BAP, a BPP, and the Beckn Fabric services that tie them together. No prior beckn experience needed. * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#what-will-you-learn) What Will You Learn? By the end of this guide you will have: 1. **A running beckn network** β€” a Consumer Node (consumer-side platform), a Provider Node (provider-side platform), and the ONIX adapters that connect them, all running in your own environment, local or cloud. You will also see how the **Discovery Service** serves `discover` requests from Consumer nodes. 2. **A working understanding of Beckn Fabric services** β€” specifically how the **DeDi Registry** is used for identity and routing, and how the **Catalog Service** lets a Provider node publish its offerings. 3. **An observable transaction flow** β€” you will fire real beckn API calls, see the messages get signed and routed, and watch the full `discover β†’ select β†’ init β†’ confirm` lifecycle play out end-to-end. * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#what-is-beckn-a-quick-recap) What is Beckn? β€” A Quick Recap **Beckn** is an open protocol that allows any buyer-side application to transact with any provider-side application across an open network β€” without either side being locked into a single platform. Think of it like HTTP for transactions: as long as both sides speak the beckn protocol, they can discover each other, negotiate, and transact, regardless of who built them. Every beckn network has two kinds of application participants: * **Consumer Node (also known as BAP - Beckn Application Platform)** β€” the consumer side. A BAP initiates transactions by sending actions: `discover`, `select`, `init`, `confirm`, and so on. * **Provider Node (also known as BPP - Beckn Provider Platform)** β€” the provider side. A BPP responds asynchronously: `on_discover`, `on_select`, `on_init`, `on_confirm`, and so on. These two sides need not talk to each other directly. Every message travels through **ONIX adapters** β€” middleware that handles digital signing, schema validation, and protocol-level routing. It can also support observability at the network level, business policy enforcement, and much more. This keeps your application code focused on business logic. Underpinning the whole network are **Beckn Fabric** services β€” shared infrastructure that every participant relies on. This starter kit uses two Fabric services: the **DeDi Registry** (for identity and routing lookups) and the **Catalog Service** (for publishing offerings). These are covered in detail in Beckn Fabric: Registry and Catalog Service. * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#prerequisites) Prerequisites Ensure the following tools are installed before you begin: * **Git** β€” to clone this repository * **Docker** and **Docker Compose** * [Install Docker](https://docs.docker.com/engine/install/) * Docker Compose ships with Docker Desktop; for Linux see the [Compose plugin guide](https://docs.docker.com/compose/install/) * **Postman** β€” to send test requests * [Download Postman](https://www.postman.com/downloads/) For cloud VPS deployment you additionally need SSH access to a Linux server (Ubuntu 22.04 recommended) with ports 8081 and 8082 open in your firewall. * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#quick-start-run-the-network-locally) Quick Start: Run the Network Locally This is the fastest way to see a beckn network in action. Five Docker containers β€” two adapters, two application simulators, and Redis β€” start up on your laptop and form a complete, working network. **Step 1 β€” Clone the repository** **Step 2 β€” Start the stack** The first run pulls the required Docker images. This takes a few minutes once; subsequent starts are fast. **Step 3 β€” Confirm all services are healthy** Wait until all five containers show `running` or `healthy`: Service Port Status to expect `redis` 6379 `healthy` `onix-bap` 8081 `running` `onix-bpp` 8082 `running` `app-bap` 3001 `healthy` `app-bpp` 3002 `healthy` **Step 4 β€” (Optional) Watch the adapters in real time** Open a second terminal and tail the adapter logs while you send requests: You will see each message being signed, validated, and routed as you work through the transaction steps. **Stopping the stack** * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#deployment-cloud-vps) Deployment: Cloud VPS The same Docker Compose file works on any Linux VPS. Follow these steps after provisioning your server. **Recommended server spec:** 2 GB RAM, Ubuntu 22.04. **Firewall β€” open these ports:** Port Purpose 22 SSH 8081 onix-bap (BAP ONIX adapter) 8082 onix-bpp (BPP ONIX adapter) 3001 app-bap (optional β€” for direct application access) 3002 app-bpp (optional) **Install Docker on the server:** **Clone and start:** The `-d` flag runs the stack in the background. Verify with: **Make the stack survive reboots:** The `onix-bap` and `onix-bpp` containers already have `restart: unless-stopped` in the compose file. Redis and the application containers will also restart automatically once you add that policy. Run `up -d` again after any changes to the compose file. **Using a domain name and TLS:** For a production-like setup, place a reverse proxy in front of the adapters. Example with Caddy (auto-TLS via Let's Encrypt): Once your domain is live, update the routing configs (`generic-routing-BAPReceiver.yaml` and `generic-routing-BPPCaller.yaml`) with the public URLs, and register your participant with the Beckn testnet registry (see Customising the Starter Kit). * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#your-first-transaction) Your First Transaction With the stack running, import the Postman collections and walk through a complete beckn transaction. **Import the collections** 1. Open Postman and click **Import**. 2. Navigate to `starter-kit/generic-devkit/postman/`. 3. Import both files: * `BAPBecknStarterKit.postman_collection.json` β€” the buyer side * `BPPBecknStarterKit.postman_collection.json` β€” the provider side **Set the collection variables** Each collection has a `bap_adapter_url` / `bpp_adapter_url` variable that tells Postman where the ONIX adapters are reachable. For local deployment: * `bap_adapter_url` β†’ `http://localhost:8081/bap/caller` * `bpp_adapter_url` β†’ `http://localhost:8082/bpp/caller` For a VPS, replace `localhost` with your server's IP or domain. **Run in this order** The two collections together cover everything a BAP and a BPP need to do. Run them in this sequence: The `on_*` callbacks (`on_discover`, `on_select`, `on_init`, `on_confirm`) are sent asynchronously by the network and received automatically by the applications β€” you do not need to trigger them manually. The BPP collection also contains `on_select`, `on_init`, and `on_confirm` requests if you want to simulate or inspect the BPP responses manually. After each step, check the `onix-bap` and `onix-bpp` logs to see the message being processed. * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#how-it-all-works) How It All Works Now that you have seen the network in action, here is a deeper look at how the pieces fit together. #### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#the-services-in-this-stack) The Services in This Stack Service Image Port Role `onix-bap` `fidedocker/onix-adapter` 8081 BAP-side protocol adapter `onix-bpp` `fidedocker/onix-adapter` 8082 BPP-side protocol adapter `app-bap` `fidedocker/sandbox-2.0` 3001 Simulates a BAP application `app-bpp` `fidedocker/sandbox-2.0` 3002 Simulates a BPP application `redis` `redis:alpine` 6379 Shared request/response cache **The ONIX adapter** (`fidedocker/onix-adapter`) is the core middleware from the [beckn-onix](https://github.com/beckn/beckn-onix) project. It is a plugin-based Go server that handles signing, signature validation, schema validation, and routing for every beckn message. Both `onix-bap` and `onix-bpp` run the same binary β€” their behaviour is entirely determined by their config files. **The application simulator** (`fidedocker/sandbox-2.0`) is a generic beckn application simulator. It exposes simple HTTP endpoints that receive forwarded messages and generate appropriate responses, so you can observe the full protocol flow without building your own Consumer node or Provider node app yet. #### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#beckn-fabric-registry-and-catalog-service) Beckn Fabric: Registry and Catalog Service **Beckn Fabric** is the shared infrastructure layer that makes an open beckn network possible. Without Fabric, each participant would need bilateral agreements with every other participant. Fabric removes that requirement by providing shared, trustless services that the whole network relies on. This starter kit uses two Beckn Fabric services, both hosted at `fabric.nfh.global`, plus an independent Discovery Service that runs alongside but outside of Fabric: **DeDi Registry** (`fabric.nfh.global/registry/dedi`) The DeDi (Decentralised Discovery) Registry is the source of truth for participant identity on the network. Every Consumer node and Provider node registers their network ID, public key, and callback URI with the registry. The ONIX adapter consults the registry for two things: * **Signature validation** β€” when an inbound message arrives, the adapter looks up the sender's public key in the registry to verify the digital signature. If the key is not found or the signature is invalid, the message is rejected. * **Routing** β€” when a message needs to reach a Provider node (e.g., `select`) or return to a Consumer node (e.g., `on_select`), the adapter performs a registry lookup by participant ID to resolve the correct callback URL. This is how the network routes messages without any static config between participants. The registry is referenced in all four adapter config files under the `registry` plugin: **Catalog Service** (`fabric.nfh.global/beckn/catalog`) The Catalog Service is where Provider nodes publish their offerings. When a Provider node calls `publish` (via `onix-bpp`), the adapter signs the message and forwards it to the Catalog Service. The Catalog Service stores the offering and responds with an `on_publish` callback to the Provider node. This is how a Provider node makes its catalog available for discovery without needing a direct connection to any Consumer node. The Catalog Service endpoint is configured in `generic-routing-BPPCaller.yaml`: **Discovery Service** (``) The Discovery Service is an independent network service β€” not part of Beckn Fabric β€” that acts as the search engine for the network. It queries the catalogs that Provider nodes have published to the Fabric Catalog Service and serves matching results to Consumer nodes. When a Consumer node sends a `discover` request, the adapter routes it to the Discovery Service, which responds asynchronously with an `on_discover` callback. The Consumer node never contacts a Provider node directly during discovery β€” direct Consumer-to-Provider communication only begins at `select`. The Discovery Service endpoint is configured in `generic-routing-BAPCaller.yaml`: #### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#the-full-transaction-flow) The Full Transaction Flow Here is the complete picture of how a beckn transaction flows through the network, showing the correct roles of the two Beckn Fabric services and the Discovery Service: The key insight: **discovery always goes through the Discovery Service** (BAP β†’ Discovery Service), and **post-discovery transactions flow directly between BAP and BPP** with the DeDi Registry providing dynamic routing. The BPP also uses Fabric to publish its catalog before any discovery can happen. #### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#tracing-a-request-end-to-end) Tracing a Request End-to-End Here is the step-by-step journey of a single `discover` call, showing what happens inside each service: **1\. Postman β†’ onix-bap** You trigger a `discover` by POSTing to onix-bap's caller endpoint (`/bap/caller/discover`). The `bapTxnCaller` module picks it up. **2\. addRoute** β€” the adapter reads `generic-routing-BAPCaller.yaml` and matches the `discover` action to the configured Discovery Service URL. **3\. sign** β€” the adapter signs the request body using the Ed25519 private key defined under `keyManager` in `generic-bap.yaml` (identity: `bap.example.com`). **4\. validateSchema** β€” the Beckn v2.0.0 OpenAPI spec is fetched from GitHub (cached for 1 hour) and the message is validated against it. **5\. Request β†’ Discovery Service** β€” the signed, validated `discover` message is forwarded to the Discovery Service. **6\. Discovery Service β†’ on\_discover callback** β€” the Discovery Service searches its catalog index and asynchronously POSTs `on_discover` back to onix-bap's receiver endpoint (`/bap/receiver/on_discover`). **7\. validateSign** β€” the `bapTxnReceiver` module verifies the Discovery Service's digital signature by looking up its public key in the DeDi Registry. **8\. addRoute** β€” reads `generic-routing-BAPReceiver.yaml`, which routes all `on_*` callbacks to the app-bap webhook. **9\. app-bap receives on\_discover** β€” the response (list of available offerings) is now stored in the application and visible in logs. For `select`, `init`, and `confirm`, the flow is similar but the adapter uses the DeDi Registry to resolve the BPP's URI dynamically (no hardcoded URL needed), and onix-bpp uses the registry to resolve the BAP's callback URI for the `on_*` responses. * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#repository-structure) Repository Structure #### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#config-how-each-file-is-used) config/ β€” How Each File Is Used Each ONIX adapter instance loads one primary config file, which in turn references routing config files for each module. `**generic-bap.yaml**` β€” loaded by onix-bap. Defines two modules: * `bapTxnCaller` at `/bap/caller/` handles **outbound** Consumer node requests. It signs each message, routes it using `generic-routing-BAPCaller.yaml`, and validates the schema. * `bapTxnReceiver` at `/bap/receiver/` handles **inbound** `on_*` callbacks. It validates the sender's signature (via DeDi Registry lookup), routes the response to app-bap using `generic-routing-BAPReceiver.yaml`, and validates the schema. `**generic-bpp.yaml**` β€” loaded by onix-bpp. Defines two modules: * `bppTxnReceiver` at `/bpp/receiver/` handles **inbound** action requests from Consumer nodes. It validates signatures and routes to app-bpp using `generic-routing-BPPReceiver.yaml`. * `bppTxnCaller` at `/bpp/caller/` handles **outbound** `on_*` responses and `publish` calls. It signs messages and routes them using `generic-routing-BPPCaller.yaml`. `**generic-routing-BAPCaller.yaml**` β€” outbound routing for the Consumer node: * `discover` β†’ routes to the Discovery Service (`https:///beckn`) * All transaction actions (`select`, `init`, `confirm`, `status`, `track`, `update`, `cancel`, `rate`, `support`) β†’ `targetType: bpp`, resolved dynamically via DeDi Registry lookup `**generic-routing-BAPReceiver.yaml**` β€” all inbound `on_*` callbacks are routed to app-bap's webhook endpoint. `**generic-routing-BPPReceiver.yaml**` β€” all inbound action requests and `on_publish` callbacks are routed to app-bpp's webhook endpoint. `**generic-routing-BPPCaller.yaml**` β€” outbound routing for the BPP: * All `on_*` responses (`on_select`, `on_init`, `on_confirm`, etc.) β†’ `targetType: bap`, resolved dynamically via DeDi Registry lookup * `publish` β†’ routes to the Fabric Catalog Service (`https://fabric.nfh.global/beckn/catalog`) Both config files embed a `**keyManager**` section with pre-generated Ed25519 key pairs for testnet participants `bap.example.com` and `bpp.example.com`. These are registered with the DeDi Registry on `beckn.one/testnet` and work out of the box β€” no changes needed to get started. #### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#postman-what-the-collections-do) postman/ β€” What the Collections Do `**BAPBecknStarterKit.postman_collection.json**` β€” the buyer-side flows, organised in two folders: * **1 β€” Discovery:** `discover` β€” sent to onix-bap (`/bap/caller/discover`), which routes it to the Discovery Service. * **2 β€” Transaction:** `select` β†’ `init` β†’ `confirm` β€” sent to onix-bap, which routes each to the BPP via DeDi Registry lookup. `**BPPBecknStarterKit.postman_collection.json**` β€” the provider-side flows, organised in two folders: * **1 β€” Transaction:** `on_select`, `on_init`, `on_confirm` β€” sent to onix-bpp (`/bpp/caller/on_*`). Use these to manually simulate or inspect BPP responses. In a normal flow app-bpp handles these automatically. * **2 β€” Catalog Publishing:** `publish` β€” sent to onix-bpp (`/bpp/caller/publish`), which routes it to the Fabric Catalog Service. Run this before `discover` to populate the catalog. * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#customising-the-starter-kit) Customising the Starter Kit **Changing the Discovery Service or Catalog Service endpoint** Edit `config/generic-routing-BAPCaller.yaml` to point `discover` at a different Discovery Service. Edit `config/generic-routing-BPPCaller.yaml` to point `publish` at a different Catalog Service endpoint. **Running fully offline (no external dependencies)** Change the `discover` target in `generic-routing-BAPCaller.yaml` to route directly to onix-bpp's receiver endpoint (`http://onix-bpp:8082/bpp/receiver/`). You will also need to remove or stub the DeDi Registry lookups for the routing to work without network access. **Using your own participant identity** The config files contain pre-generated testnet key pairs for `bap.example.com` and `bpp.example.com`, registered on `beckn.one/testnet`. To use your own identity: 1. Generate a new Ed25519 key pair. 2. Register your `networkParticipant` domain and public key with the DeDi Registry at `fabric.nfh.global/registry/dedi`. 3. Update the `keyManager` section in `generic-bap.yaml` and `generic-bpp.yaml` with your new participant ID, key ID, and key material. 4. Update the routing config files to use your `networkId` in place of `beckn.one/testnet`. **Replacing the application simulator with your own application** The application simulator containers (`app-bap` and `app-bpp`) are simple simulators. Replace either with your own application by updating the service image and webhook URLs in the compose file and routing configs. Your application needs to accept POSTed beckn messages at the configured endpoints and be on the same Docker network. **Using a different beckn domain** Update the `domain` (or `networkId`) field in all four routing YAML files to match your domain. Point the `schemav2validator` in the adapter config to the appropriate OpenAPI spec URL for schema validation. * * * ### [](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#troubleshooting) Troubleshooting **Containers fail to start** Check for port conflicts on 8081, 8082, 3001, 3002, or 6379: **app-bap or app-bpp stays in** `**starting**` **state** The application containers health-check at `/api/health`. If they don't reach `healthy` within about a minute, inspect their logs. Note that the Docker container names in the compose file are `sandbox-bap` and `sandbox-bpp` (use those in Docker commands even though we refer to them conceptually as `app-bap` / `app-bpp`): **Postman requests return connection errors** Confirm the stack is fully up (`docker compose ps` shows all five containers as `running` or `healthy`) and that your Postman collection variables point to the right host and port. **Signature validation failures (**`**validateSign**` **errors in logs)** The most common cause is clock skew. Beckn signatures embed a timestamp with a short validity window. On Linux: `timedatectl` to check clock sync. On Docker Desktop, ensure the VM clock is synchronised. `**discover**` **returns no results** The Discovery Service must be reachable. Check the URL configured in `generic-routing-BAPCaller.yaml` and test connectivity with: If it times out, the testnet may be temporarily unavailable, or your network may block outbound HTTPS. Also check whether `publish` was called first β€” the Discovery Service can only return results for offerings that have been published to the Catalog Service. `**publish**` **or** `**on_publish**` **not working** Confirm the Catalog Service endpoint in `generic-routing-BPPCaller.yaml` is reachable (`curl -s https://fabric.nfh.global/beckn/catalog`). Also verify the BPP's signing keys are valid by reviewing the `keyManager` section in `generic-bpp.yaml`. **Images fail to pull** Ensure Docker has at least 2 GB RAM allocated and a stable internet connection for pulling the required images. **Stopping and cleaning up** [PreviousConnect to everything using Beckn ONIX](https://docs.nfh.global/beckn/introduction-to-beckn/fabric-the-value-exchange-infrastructure/connect-to-everything-using-beckn-onix) [NextSetting up the network environment](https://docs.nfh.global/beckn/creating-an-open-network/setting-up-the-network-environment) Last updated 21 days ago Was this helpful? * [What Will You Learn?](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#what-will-you-learn) * [What is Beckn? β€” A Quick Recap](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#what-is-beckn-a-quick-recap) * [Prerequisites](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#prerequisites) * [Quick Start: Run the Network Locally](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#quick-start-run-the-network-locally) * [Deployment: Cloud VPS](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#deployment-cloud-vps) * [Your First Transaction](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#your-first-transaction) * [How It All Works](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#how-it-all-works) * [Repository Structure](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#repository-structure) * [Customising the Starter Kit](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#customising-the-starter-kit) * [Troubleshooting](https://docs.nfh.global/beckn/experience-beckn/getting-started-with-beckn#troubleshooting) Was this helpful? GitBook AssistantAskCopy git clone https://github.com/beckn/starter-kit.git cd starter-kit/generic-devkit/install GitBook AssistantAskCopy docker compose -f docker-compose-generic.yml up GitBook AssistantAskCopy docker compose -f docker-compose-generic.yml ps GitBook AssistantAskCopy docker compose -f docker-compose-generic.yml logs -f onix-bap onix-bpp GitBook AssistantAskCopy docker compose -f docker-compose-generic.yml down GitBook AssistantAskCopy ssh user@your-server-ip curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker GitBook AssistantAskCopy git clone https://github.com/beckn/starter-kit.git cd starter-kit/generic-devkit/install docker compose -f docker-compose-generic.yml up -d GitBook AssistantAskCopy docker compose -f docker-compose-generic.yml ps docker compose -f docker-compose-generic.yml logs --tail=50 GitBook AssistantAskCopy bap.yourdomain.com { reverse_proxy localhost:8081 } bpp.yourdomain.com { reverse_proxy localhost:8082 } GitBook AssistantAskCopy [BPP] publish ← BPP registers its catalog with the Catalog Service [BAP] discover ← BAP queries the Discovery Service for available offerings [BAP] select ← BAP selects a specific offering [BAP] init ← BAP initiates the order [BAP] confirm ← BAP confirms the transaction GitBook AssistantAskCopy β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Your Environment β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ app-bap │◄───►│ onix-bap (port 8081) β”‚ β”‚ β”‚ β”‚ BAP app β”‚ β”‚ BAP-side ONIX adapter β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ /bap/caller/ /bap/receiver/ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ app-bpp │◄───►│ onix-bpp (port 8082) β”‚ β”‚ β”‚ β”‚ BPP app β”‚ β”‚ BPP-side ONIX adapter β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ /bpp/receiver/ /bpp/caller/ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ β”‚ redis (shared cache, port 6379) β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Beckn Fabric β”‚ β”‚ Discovery Service β”‚ β”‚ β”‚ β”‚ (independent service) β”‚ β”‚ DeDi Registry β”‚ β”‚ β”‚ β”‚ Β· Identity lookups β”‚ β”‚ Receives discover from β”‚ β”‚ Β· Dynamic routing β”‚ β”‚ BAPs, queries Fabric β”‚ β”‚ (resolves BAP/BPP URIs) β”‚ β”‚ catalog, returns β”‚ β”‚ β”‚ β”‚ on_discover β”‚ β”‚ Catalog Service β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ Β· BPP publishes offerings β”‚ β”‚ Β· Feeds Discovery Service β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ GitBook AssistantAskCopy registry: id: dediregistry config: url: https://fabric.nfh.global/registry/dedi registryName: subscribers.beckn.one GitBook AssistantAskCopy target: url: "https://fabric.nfh.global/beckn/catalog" endpoints: - publish GitBook AssistantAskCopy target: url: "https:///beckn" endpoints: - discover GitBook AssistantAskCopy Provider node side β€” catalog setup (happens before any Consumer node transaction) ───────────────────────────────────────────────────────────────── app-bpp ──publish──► onix-bpp ──publish──► Catalog Service (Fabric) β”‚ app-bpp ◄──on_publish── onix-bpp ◄──on_publishβ”€β”€β”€β”€β”€β”˜ (catalog accepted; BPP offerings are now discoverable) BAP side β€” discovery ───────────────────────────────────────────────────────────────── app-bap ──discover──► onix-bap ──discover──► Discovery Service β”‚ (queries Fabric catalog) β”‚ app-bap ◄──on_discover── onix-bap ◄──on_discoverβ”€β”€β”€β”˜ (BAP receives list of matching offerings) BAP ↔ BPP β€” transaction (select / init / confirm) ───────────────────────────────────────────────────────────────── app-bap ──select──► onix-bap β”‚ DeDi Registry resolves BPP URI β–Ό onix-bpp ──► app-bpp β”‚ app-bpp sends on_select response β”‚ onix-bpp β”‚ DeDi Registry resolves BAP URI β–Ό app-bap ◄──on_select── onix-bap ... same pattern repeats for init / confirm ... GitBook AssistantAskCopy starter-kit/ β”‚ └── generic-devkit/ β”‚ β”œβ”€β”€ config/ # All adapter configuration β”‚ β”œβ”€β”€ generic-bap.yaml # BAP adapter: modules, plugins, keys β”‚ β”œβ”€β”€ generic-bpp.yaml # BPP adapter: modules, plugins, keys β”‚ β”œβ”€β”€ generic-routing-BAPCaller.yaml # Where BAP sends outbound requests β”‚ β”œβ”€β”€ generic-routing-BAPReceiver.yaml # Where BAP delivers incoming callbacks β”‚ β”œβ”€β”€ generic-routing-BPPCaller.yaml # Where BPP sends outbound responses β”‚ └── generic-routing-BPPReceiver.yaml # Where BPP delivers incoming requests β”‚ β”œβ”€β”€ install/ β”‚ β”œβ”€β”€ docker-compose-generic.yml # Main compose file (pre-built adapter image) β”‚ └── docker-compose-generic-local.yml # Alternate compose file (locally built image) β”‚ └── postman/ β”œβ”€β”€ BAPBecknStarterKit.postman_collection.json # BAP-side flows └── BPPBecknStarterKit.postman_collection.json # BPP-side flows GitBook AssistantAskCopy docker compose -f docker-compose-generic.yml logs GitBook AssistantAskCopy docker compose -f docker-compose-generic.yml logs sandbox-bap docker compose -f docker-compose-generic.yml logs sandbox-bpp GitBook AssistantAskCopy curl -s https:///beckn GitBook AssistantAskCopy # Stop containers docker compose -f docker-compose-generic.yml down # Stop and remove volumes and image cache docker compose -f docker-compose-generic.yml down -v --- # API Reference | DeDi | NFH Fabric [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#base-url) Base URL -------------------------------------------------------------------------------------------- All API requests should be made to: GitBook AssistantAskCopy https://api.dedi.global [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#authentication) Authentication -------------------------------------------------------------------------------------------------------- Before using any DeDi.global APIs, you need to obtain an API key for authentication. Most APIs require authentication except for public lookup and query operations. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#getting-your-api-key) Getting Your API Key 1. **Navigate to the DeDi.global Platform** Go to [https://publish.dedi.global](https://publish.dedi.global/) 2. **Register or Login** * **First-time users**: Click "Register" and provide: * Name * Email address * Password (minimum 6 characters with special characters) * **Existing users**: Click "Login" with your credentials 3. **Email Verification** Check your email for a magic link and click it to verify your account (Multi-Factor Authentication) 4. **Generate API Key** * Once logged in, click the profile button in the top-right corner * Select "Get API Key" * Copy the generated API key for use in your applications > **Note**: You can attach screenshots of the registration flow, login interface, and API key generation process to help users navigate the platform more easily. Place images in an `assets/` folder and reference them using relative paths. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#using-your-api-key) Using Your API Key Include your API key in all authenticated requests as a Bearer token in the Authorization header: **Authentication Status**: Each API endpoint in this documentation is clearly marked with: * πŸ”’ **Authentication Required** - Must include API key * 🌐 **Public Access** - No authentication needed [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#api-sections-overview) API Sections Overview ---------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#publish-apis) [Publish APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish) Create and manage the core components of your data infrastructure on DeDi.global. * **Namespace Management**: Create isolated environments to organize your data * **Registry Creation**: Define structured schemas for data collection * **Record Management**: Store, draft, and publish individual data records * **Bulk Operations**: Handle large-scale data uploads via CSV files * **Data Export**: Extract registry data for analysis and backup ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#access-apis) [Access APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access) Query and retrieve data from the DeDi.global network with powerful search capabilities. * **Lookup Operations**: Direct access to specific entities using identifiers * **Query Interface**: Advanced filtering and pagination across namespaces and registries * **Version History**: Access historical data and track changes over time * **Schema Discovery**: Find registries by standardized schema tags ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#domain-verification) [Domain Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain) Establish domain ownership to build trust and enhance namespace credibility. * **DNS TXT Generation**: Create unique verification records for domains * **Domain Ownership Verification**: Validate control through DNS validation * **Trust Enhancement**: Increase user confidence through verified domain status * **Verification Monitoring**: Track and confirm verification progress ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#delegation-management) [Delegation Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation) Enable collaborative access and team-based workflows through controlled permission sharing. * **Namespace Delegation**: Grant administrative access to entire namespaces for broad control * **Registry Delegation**: Provide specific registry management permissions for focused collaboration * **Access Control**: Manage team permissions with principle of least privilege * **Organizational Workflows**: Support complex organizational structures and project-based access patterns ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#update-management) [Update Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update) Modify existing data while maintaining integrity and audit trails. * **Record Updates**: Edit records with version tracking * **Registry Modifications**: Update description and metadata * **Namespace Changes**: Modify namespace properties and settings ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#state-management) [State Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management) Control the lifecycle and availability of your data. * **State Control**: Manage namespace, registry, and record lifecycle * **Recovery Operations**: Delete and restore namespaces, registries, and records * **Retention Window**: Restore deleted entities before permanent archival ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#advanced-search) [Advanced Search](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search) Powerful search capabilities across the entire namespaces. * **Cross-Registry Search**: Query multiple registries simultaneously * **Filtering Options**: Apply complex filters to narrow results * **Aggregation Queries**: Perform analytical operations on data sets ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#subscription) [Subscription](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/subscription) Stay informed about changes to data you care about. * **Webhook Integration**: Receive real-time notifications of changes * **Event Filtering**: Subscribe to specific types of updates * **Subscription Management**: Control your notification preferences ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#lookup-verification) [Lookup Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification) Advanced verification and data integrity operations. * **Cryptographic Verification**: Validate data authenticity and integrity * **Trust Chain Analysis**: Understand the verification path of data * **Compliance Checking**: Ensure data meets required standards [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#error-handling) Error Handling -------------------------------------------------------------------------------------------------------- All APIs follow consistent error response patterns: Common HTTP status codes: * `200` - Success * `400` - Bad Request (invalid parameters) * `401` - Unauthorized (missing or invalid API key) * `403` - Forbidden (insufficient permissions) * `404` - Not Found (resource doesn't exist) * `429` - Rate Limit Exceeded * `500` - Internal Server Error [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#getting-started) Getting Started ---------------------------------------------------------------------------------------------------------- 1. [Obtain your API key](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#authentication) from the DeDi.global platform 2. Start with [Publish APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish) to create your first namespace and registry 3. Use [Access APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access) to query and retrieve your data 4. Explore [advanced features](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain) like domain verification and webhooks [PreviousDomain Verification - The bedrock of trust in DeDi](https://docs.nfh.global/dedi/dedi.global-developers/quickstart/domain-verification-the-bedrock-of-trust-in-dedi) [NextPublish APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish) Last updated 1 month ago Was this helpful? * [Base URL](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#base-url) * [Authentication](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#authentication) * [Getting Your API Key](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#getting-your-api-key) * [Using Your API Key](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#using-your-api-key) * [API Sections Overview](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#api-sections-overview) * [Publish APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#publish-apis) * [Access APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#access-apis) * [Domain Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#domain-verification) * [Delegation Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#delegation-management) * [Update Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#update-management) * [State Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#state-management) * [Advanced Search](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#advanced-search) * [Subscription](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#subscription) * [Lookup Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#lookup-verification) * [Error Handling](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#error-handling) * [Getting Started](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis#getting-started) Was this helpful? GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/endpoint', { method: 'GET', headers: { 'Authorization': `Bearer ${your_api_key}`, 'Content-Type': 'application/json' } }); GitBook AssistantAskCopy { "error": { "code": "ERROR_CODE", "message": "Human-readable error description", "details": { // Additional context when available } } } --- # State Management | DeDi | NFH Fabric DeDi.global manages resource lifecycle through explicit namespace, registry, and record states, plus dedicated deletion and recovery APIs. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#state-model) State Model ------------------------------------------------------------------------------------------------------------------- Entity Supported states Notes Namespace `live` A namespace remains `live` until it is deleted. Registry `live`, `inactive` Inactive registries remain versioned and restorable. Record `draft`, `live` Draft records are private working versions. Published records are `live`. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#transition-rules) Transition Rules ----------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#namespace) Namespace * New namespaces are created in the `live` state. * A namespace does not transition to another active state. * Namespace removal is handled through the deletion and restore APIs. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#registry) Registry * New registries are created in the `live` state. * `POST /dedi/{namespace}/{registry_name}/inactivate-registry` creates a new registry version in the `inactive` state. * `POST /dedi/{namespace}/{registry_name}/reactivate-registry` creates a new registry version in the `live` state. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#record) Record * `POST /dedi/{namespace}/{registry_name}/save-record-as-draft` creates a draft record. * `POST /dedi/{namespace}/{registry_name}/publish-records` publishes draft records to the `live` state. * Updating a draft record edits the draft version. * Updating a live record creates a new live version. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#registry-activation-apis) Registry Activation APIs --------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#inactivate-registry) Inactivate Registry **Endpoint:** `POST /dedi/{namespace}/{registry_name}/inactivate-registry` **Request Body:** None **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#reactivate-registry) Reactivate Registry **Endpoint:** `POST /dedi/{namespace}/{registry_name}/reactivate-registry` **Request Body:** None **Success Response (200):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#deletion-apis) Deletion APIs ----------------------------------------------------------------------------------------------------------------------- Deletion removes the active entity from lookup, query, version, and publish flows and places the deleted data into the recovery surface for a limited restore window. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#delete-namespace) Delete Namespace **Endpoint:** `DELETE /dedi/{namespace}/delete-namespace` **Request Body:** **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#delete-registry) Delete Registry **Endpoint:** `DELETE /dedi/{namespace}/{registry_name}/delete-registry` **Request Body:** **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#delete-records) Delete Records **Endpoint:** `DELETE /dedi/{namespace}/{registry_name}/delete-records` **Request Body:** **Success Response (200):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#deleted-entity-listing-apis) Deleted Entity Listing APIs --------------------------------------------------------------------------------------------------------------------------------------------------- These endpoints return the latest deleted snapshot that is still eligible for restoration. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#list-deleted-namespaces) List Deleted Namespaces **Endpoint:** `GET /dedi/deleted/namespaces` **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#list-deleted-registries) List Deleted Registries **Endpoint:** `GET /dedi/deleted/registries` **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#list-deleted-records) List Deleted Records **Endpoint:** `GET /dedi/deleted/records` **Success Response (200):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#restore-apis) Restore APIs --------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#restore-namespace) Restore Namespace **Endpoint:** `POST /dedi/restore/namespace` **Request Body:** **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#restore-registry) Restore Registry **Endpoint:** `POST /dedi/restore/registry` **Request Body:** **Success Response (200):** **Important:** If multiple deleted histories exist for the same registry name, `deleted_history_id` is required. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#restore-records) Restore Records **Endpoint:** `POST /dedi/restore/records` **Request Body:** **Success Response (200):** **Important:** If multiple deleted histories exist for the same record name, `deleted_history_id` is required. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#deleted-entity-retention-window) Deleted Entity Retention Window ----------------------------------------------------------------------------------------------------------------------------------------------------------- * Deleted namespaces, registries, and records remain restorable during the deleted-entity retention window. * The current implementation keeps deleted entities in the recovery surface for a configurable retention period. * The default retention period is `3` days. * After the retention window expires, deleted entities are moved to permanent archival storage and can no longer be restored through the public APIs. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#related-apis) Related APIs --------------------------------------------------------------------------------------------------------------------- * Publishing and draft-to-live flows: [Publish APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish) * Versioned edits: [Update APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update) * Domain trust lifecycle: [Domain Verification APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain) * Delegation and namespace ownership changes: [Delegation Management APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation) [PreviousUpdate Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update) [NextAdvanced Search](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search) Last updated 1 month ago Was this helpful? * [State Model](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#state-model) * [Transition Rules](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#transition-rules) * [Namespace](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#namespace) * [Registry](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#registry) * [Record](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#record) * [Registry Activation APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#registry-activation-apis) * [Inactivate Registry](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#inactivate-registry) * [Reactivate Registry](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#reactivate-registry) * [Deletion APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#deletion-apis) * [Delete Namespace](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#delete-namespace) * [Delete Registry](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#delete-registry) * [Delete Records](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#delete-records) * [Deleted Entity Listing APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#deleted-entity-listing-apis) * [List Deleted Namespaces](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#list-deleted-namespaces) * [List Deleted Registries](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#list-deleted-registries) * [List Deleted Records](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#list-deleted-records) * [Restore APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#restore-apis) * [Restore Namespace](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#restore-namespace) * [Restore Registry](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#restore-registry) * [Restore Records](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#restore-records) * [Deleted Entity Retention Window](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#deleted-entity-retention-window) * [Related APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management#related-apis) Was this helpful? GitBook AssistantAskCopy { "message": "Registry has been inactivated" } GitBook AssistantAskCopy { "message": "Registry has been reactivated" } GitBook AssistantAskCopy { "reason": "Optional deletion reason" } GitBook AssistantAskCopy { "message": "Namespace deleted successfully", "data": { "namespace_id": "did:cord:...", "deleted_namespace_versions": 3, "deleted_registry_versions": 8, "deleted_record_versions": 42 } } GitBook AssistantAskCopy { "reason": "Optional deletion reason" } GitBook AssistantAskCopy { "message": "Registry deleted successfully", "data": { "registry_name": "employee-profiles", "deleted_registry_versions": 4, "deleted_record_versions": 17 } } GitBook AssistantAskCopy { "records": ["record-a", "record-b"], "reason": "Optional deletion reason" } GitBook AssistantAskCopy { "message": "Records deleted successfully", "data": { "count": 2, "deleted_record_versions": 5, "records": ["record-a", "record-b"] } } GitBook AssistantAskCopy { "message": "Deleted namespaces fetched successfully", "data": [\ {\ "namespace_id": "did:cord:...",\ "name": "acme",\ "state": "live",\ "deleted_at": "2026-05-04T08:30:00.000Z",\ "deleted_by": "did:cord:profile:...",\ "delete_scope": "namespace",\ "reason": "Cleanup"\ }\ ] } GitBook AssistantAskCopy { "message": "Deleted registries fetched successfully", "data": [\ {\ "namespace_id": "did:cord:...",\ "registry_id": "did:cord:registry:...",\ "registry_name": "employee-profiles",\ "state": "inactive",\ "deleted_history_id": "did:cord:registry:...",\ "deleted_at": "2026-05-04T08:30:00.000Z",\ "deleted_by": "did:cord:profile:...",\ "delete_scope": "registry",\ "reason": "Cleanup"\ }\ ] } GitBook AssistantAskCopy { "message": "Deleted records fetched successfully", "data": [\ {\ "namespace_id": "did:cord:...",\ "registry_name": "employee-profiles",\ "record_id": "did:cord:record:...",\ "record_name": "john-doe",\ "state": "live",\ "deleted_history_id": "did:cord:record:...",\ "deleted_at": "2026-05-04T08:30:00.000Z",\ "deleted_by": "did:cord:profile:...",\ "delete_scope": "record",\ "reason": "Cleanup"\ }\ ] } GitBook AssistantAskCopy { "namespace_id": "did:cord:..." } GitBook AssistantAskCopy { "message": "Namespace restored successfully", "data": { "namespace_id": "did:cord:...", "restored_namespace_versions": 3 } } GitBook AssistantAskCopy { "namespace_id": "did:cord:...", "registry_name": "employee-profiles", "deleted_history_id": "did:cord:registry:..." } GitBook AssistantAskCopy { "message": "Registry restored successfully", "data": { "namespace_id": "did:cord:...", "registry_name": "employee-profiles", "restored_registry_versions": 4 } } GitBook AssistantAskCopy { "records": [\ {\ "namespace_id": "did:cord:...",\ "registry_name": "employee-profiles",\ "record_name": "john-doe",\ "deleted_history_id": "did:cord:record:..."\ }\ ] } GitBook AssistantAskCopy { "message": "Records restored successfully", "data": { "restored_record_versions": 2, "records": [\ {\ "namespace_id": "did:cord:...",\ "registry_name": "employee-profiles",\ "record_name": "john-doe",\ "deleted_history_id": "did:cord:record:..."\ }\ ] } } --- # Advanced Search | DeDi | NFH Fabric DeDi.global provides powerful search capabilities across records within a namespace. The search functionality allows you to query records using registry filters, field-specific criteria, and nested JSON field exploration. **Authentication**: 🌐 The search endpoint is available as a public read API. Authentication is optional. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#core-search-concepts) Core Search Concepts ------------------------------------------------------------------------------------------------------------------------------------ * **Namespace-scoped search**: Search is always performed within a specific namespace * **Global search limitation**: Cross-namespace search is not supported for security and performance reasons * **Latest records only**: Search returns only the latest version of each record * **Flexible field matching**: Support for both direct field searches and nested JSON field queries * **Partial matching**: All text searches use case-insensitive partial matching [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#search-records-in-namespace) Search Records in Namespace -------------------------------------------------------------------------------------------------------------------------------------------------- Search for records across an entire namespace with flexible filtering capabilities. **Endpoint:** `GET /dedi/search/{namespace}` ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#parameters) Parameters **Path Parameters:** * `namespace` (required) - Namespace ID or domain to search within **Query Parameters (all optional):** * `registry_name` - Filter by registry name (partial match) * `record_name` - Search by record name (partial match) * `from` - Filter records created/updated after this date (ISO 8601 format) * `to` - Filter records created/updated before this date (ISO 8601 format) * Any field from record details - Search by specific field values ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#field-search-capabilities) Field Search Capabilities The search API supports searching within the JSON `details` field of records: **Direct Field Search:** * `[[emailΒ protected]](https://docs.nfh.global/cdn-cgi/l/email-protection) ` - Searches `record.details.email` * `publicKey=abc123` - Searches `record.details.publicKey` * `name=john` - Searches `record.details.name` **Nested Field Search (Dot Notation):** * `profile.name=john` - Searches `record.details.profile.name` * `[[emailΒ protected]](https://docs.nfh.global/cdn-cgi/l/email-protection) ` - Searches `record.details.contact.email` * `verification.status=verified` - Searches `record.details.verification.status` * `metadata.tags.category=finance` - Searches `record.details.metadata.tags.category` [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#example-record-schema-and-search-demonstrations) Example Record Schema and Search Demonstrations ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ To demonstrate the search capabilities, let's use a comprehensive employee profile record that showcases all the different search patterns supported by the API. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#sample-employee-profile-record) Sample Employee Profile Record Consider this employee profile record stored in the `my-company` namespace: Now let's see how you can search for this record and similar records using different search patterns: [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#search-examples-using-the-sample-record) Search Examples Using the Sample Record -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-1.-basic-registry-filtering) 1\. Basic Registry Filtering Search all employee profiles in the user-profiles registry: _This would return John Doe's profile and all other user profiles_ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-2.-record-name-search) 2\. Record Name Search Find records with specific names (partial match): _This would search across all registries under 'my-company' namespace and return John Doe's profile record_ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-3.-direct-field-search) 3\. Direct Field Search Find all employees with a specific email: _This searches within_ `_record.details.email_` _and returns John Doe's profile_ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-4.-nested-field-searches) 4\. Nested Field Searches **Search by profile first name:** _This searches within_ `_record.details.profile.firstName_` **Search by profile department:** _This searches within_ `_record.details.profile.department_` _and returns all Engineering employees_ **Search by contact city:** _This searches within_ `_record.details.contact.address.city_`_. Note: Spaces in URL parameters must be URL-encoded as_ `_%20_` **Search by verification status:** _This searches within_ `_record.details.verification.status_` **Search by metadata tags:** _This searches within_ `_record.details.metadata.tags.category_`_. Note: This is not DeDi's metadata field_ **Search by team:** _This searches within_ `_record.details.metadata.tags.team_` ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-5.-combined-search-criteria) 5\. Combined Search Criteria Combine multiple search parameters for precise filtering: _This returns all senior-level employees in the Engineering department_ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-6.-time-based-filtering) 6\. Time-based Filtering Search records within date ranges: _This returns all records created or updated in 2024_ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-7.-complex-multi-criteria-search) 7\. Complex Multi-criteria Search _This returns all verified Engineering employees located in San Francisco_ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-8.-partial-text-matching) 8\. Partial Text Matching All text searches use case-insensitive partial matching: _This would still find "John" (partial match)_ _This would find "123 Tech Street" (partial match)_ [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#important-url-encoding) Important: URL Encoding ----------------------------------------------------------------------------------------------------------------------------------------- When search parameters contain spaces or special characters, they must be properly URL-encoded: * **Spaces**: Use `%20` instead of spaces * **Special characters**: Encode characters like `@`, `#`, `&`, etc. **Examples:** * `San Francisco` β†’ `San%20Francisco` * `[[emailΒ protected]](https://docs.nfh.global/cdn-cgi/l/email-protection) ` β†’ `john%40company.com` * `C++ Developer` β†’ `C%2B%2B%20Developer` Most HTTP clients and browsers handle URL encoding automatically, but when constructing URLs manually, ensure proper encoding. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#response-format) Response Format -------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#success-response-200) Success Response (200) Here's what a successful search response looks like when it returns our sample record: ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#error-responses) Error Responses **Missing Namespace (400):** **Namespace Not Found (404):** **Query Failed (500):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#search-performance-tips) Search Performance Tips ------------------------------------------------------------------------------------------------------------------------------------------ 1. **Use registry filtering**: Adding `registry_name` parameter significantly improves search performance 2. **Combine specific criteria**: Multiple specific filters are more efficient than broad searches 3. **Limit time ranges**: Use `from` and `to` parameters to narrow search scope 4. **Exact field matches**: More specific field values return faster results than partial matches [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#security-and-access-control) Security and Access Control -------------------------------------------------------------------------------------------------------------------------------------------------- * **Authentication required**: All search operations require valid authentication * **Namespace scoped**: Search results are limited to the specified namespace * **Permission based**: Only records accessible to the authenticated user are returned * **No global search**: Cross-namespace searches are not permitted for security reasons [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#real-world-use-cases) Real-World Use Cases ------------------------------------------------------------------------------------------------------------------------------------ **Employee Directory Search:** * Find employees by name, email, or department: `?profile.firstName=John` or `?email=john.doe%40company.com` * Locate team members: `?metadata.tags.team=platform` or `?profile.department=Engineering` * Find employees by location: `?contact.address.city=San%20Francisco` **HR Management:** * Search for verified employees: `?verification.status=verified` * Find employees by seniority level: `?metadata.tags.level=senior` * Locate employees by role: `?profile.title=Developer` **Access Control and Permissions:** * Find users with specific permissions: `?metadata.permissions=admin` * Search by employee category: `?metadata.tags.category=employee` * Filter by verification method: `?verification.method=email` **Compliance and Auditing:** * Search records within timeframes: `?from=2024-01-01T00:00:00Z&to=2024-12-31T23:59:59Z` * Track recent updates: `?profile.department=Engineering&from=2024-01-01T00:00:00Z` * Find records by creator: Records include `created_by` field for audit trails **Multi-criteria Filtering:** * Find senior Engineering employees in specific locations * Search verified employees with admin permissions * Locate team members by multiple attributes simultaneously The Advanced Search API provides a powerful and flexible way to query your namespace's records with support for complex field-based searches and nested JSON exploration, making it perfect for employee directory management, HR operations, and compliance reporting. [PreviousState Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management) [NextSubscription (Watch)](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/subscription) Last updated 1 month ago Was this helpful? * [Core Search Concepts](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#core-search-concepts) * [Search Records in Namespace](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#search-records-in-namespace) * [Parameters](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#parameters) * [Field Search Capabilities](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#field-search-capabilities) * [Example Record Schema and Search Demonstrations](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#example-record-schema-and-search-demonstrations) * [Sample Employee Profile Record](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#sample-employee-profile-record) * [Search Examples Using the Sample Record](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#search-examples-using-the-sample-record) * [1\. Basic Registry Filtering](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-1.-basic-registry-filtering) * [2\. Record Name Search](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-2.-record-name-search) * [3\. Direct Field Search](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-3.-direct-field-search) * [4\. Nested Field Searches](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-4.-nested-field-searches) * [5\. Combined Search Criteria](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-5.-combined-search-criteria) * [6\. Time-based Filtering](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-6.-time-based-filtering) * [7\. Complex Multi-criteria Search](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-7.-complex-multi-criteria-search) * [8\. Partial Text Matching](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#id-8.-partial-text-matching) * [Important: URL Encoding](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#important-url-encoding) * [Response Format](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#response-format) * [Success Response (200)](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#success-response-200) * [Error Responses](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#error-responses) * [Search Performance Tips](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#search-performance-tips) * [Security and Access Control](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#security-and-access-control) * [Real-World Use Cases](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/advanced-search#real-world-use-cases) Was this helpful? GitBook AssistantAskCopy { "record_name": "john-doe-profile", "registry_name": "user-profiles", "description": "John Doe's employee profile", "details": { "email": "[emailΒ protected]", "name": "John Doe", "publicKey": "0x1234567890abcdef...", "profile": { "firstName": "John", "lastName": "Doe", "title": "Senior Developer", "department": "Engineering" }, "contact": { "email": "[emailΒ protected]", "phone": "+1-555-0123", "address": { "street": "123 Tech Street", "city": "San Francisco", "country": "USA" } }, "verification": { "status": "verified", "method": "email", "verifiedAt": "2024-01-15T10:30:00Z" }, "metadata": { "tags": { "category": "employee", "level": "senior", "team": "platform" }, "permissions": ["read", "write", "admin"] } } } GitBook AssistantAskCopy GET /dedi/search/my-company?registry_name=user-profiles GitBook AssistantAskCopy GET /dedi/search/my-company?record_name=john-doe GitBook AssistantAskCopy GET /dedi/search/[emailΒ protected] GitBook AssistantAskCopy GET /dedi/search/my-company?profile.firstName=John GitBook AssistantAskCopy GET /dedi/search/my-company?profile.department=Engineering GitBook AssistantAskCopy GET /dedi/search/my-company?contact.address.city=San%20Francisco GitBook AssistantAskCopy GET /dedi/search/my-company?verification.status=verified GitBook AssistantAskCopy GET /dedi/search/my-company?metadata.tags.category=employee GitBook AssistantAskCopy GET /dedi/search/my-company?metadata.tags.team=platform GitBook AssistantAskCopy GET /dedi/search/my-company?registry_name=user-profiles&profile.department=Engineering&metadata.tags.level=senior GitBook AssistantAskCopy GET /dedi/search/my-company?from=2024-01-01T00:00:00Z&to=2024-12-31T23:59:59Z GitBook AssistantAskCopy GET /dedi/search/my-company?registry_name=user-profiles&verification.status=verified&profile.department=Engineering&contact.address.city=San%20Francisco GitBook AssistantAskCopy GET /dedi/search/my-company?profile.firstName=joh GitBook AssistantAskCopy GET /dedi/search/my-company?contact.address.street=tech GitBook AssistantAskCopy { "message": "Search results", "data": [\ {\ "record_id": "uuid-string",\ "record_name": "john-doe-profile", \ "registry_name": "user-profiles",\ "namespace_id": "my-company",\ "description": "John Doe's employee profile",\ "details": {\ "email": "[emailΒ protected]",\ "name": "John Doe",\ "publicKey": "0x1234567890abcdef...",\ "profile": {\ "firstName": "John",\ "lastName": "Doe",\ "title": "Senior Developer",\ "department": "Engineering"\ },\ "contact": {\ "email": "[emailΒ protected]",\ "phone": "+1-555-0123",\ "address": {\ "street": "123 Tech Street",\ "city": "San Francisco",\ "country": "USA"\ }\ },\ "verification": {\ "status": "verified",\ "method": "email",\ "verifiedAt": "2024-01-15T10:30:00Z"\ },\ "metadata": {\ "tags": {\ "category": "employee",\ "level": "senior",\ "team": "platform"\ },\ "permissions": ["read", "write", "admin"]\ }\ },\ "state": "live",\ "version": "v1.2.0",\ "version_count": 3,\ "genesis": "2024-01-01T00:00:00Z",\ "created_at": "2024-01-01T00:00:00Z",\ "updated_at": "2024-01-15T10:30:00Z",\ "created_by": "did:dedi:user:creator123",\ "ttl": 86400,\ "meta": {},\ "valid_till": "2025-01-01T00:00:00Z",\ "latest": true\ }\ ] } GitBook AssistantAskCopy { "message": "namespace is missing" } GitBook AssistantAskCopy { "message": "namespace not found" } GitBook AssistantAskCopy { "message": "Query failed", "error": "Database connection error" } --- # Delegation Management | DeDi | NFH Fabric Delegation is a fundamental collaboration feature that enables organizations to share control and management responsibilities across teams and departments. By distributing access permissions, organizations can maintain security while enabling efficient, scalable data management workflows. **Authentication**: πŸ”’ All Delegation Management APIs require authentication via API key. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#why-delegation-matters-in-dedi.global) Why Delegation Matters in DeDi.global ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#organizational-collaboration) Organizational Collaboration Modern organizations rarely operate with a single person controlling all data infrastructure. Different departments, teams, and roles need varying levels of access to different data sets. DeDi.global's delegation system mirrors real-world organizational structures, enabling distributed yet controlled access management. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#real-world-scenarios) Real-World Scenarios Consider a technology company "InnovateTech" that creates a namespace `innovatetech-corp` for their organization: #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#namespace-level-delegation) **Namespace-Level Delegation** The company's IT administrators and senior management need broad control across the entire namespace: * **CEO**: Full namespace access for strategic oversight * **CTO**: Technical control across all registries * **Data Protection Officer**: Compliance monitoring across departments * **IT Administrator**: Infrastructure management and user access #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#registry-level-delegation) **Registry-Level Delegation** Different departments manage their own specific data registries: * **HR Department**: Controls `employee-profiles` and `benefits-registry` * **Engineering Team**: Manages `product-specifications` and `development-milestones` * **Sales Team**: Oversees `customer-contacts` and `sales-pipeline` * **Marketing Team**: Handles `campaign-data` and `lead-generation` ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#benefits-of-delegation) Benefits of Delegation 1. **🎯 Principle of Least Privilege**: Users get exactly the access they need, nothing more 2. **⚑ Operational Efficiency**: Teams can work independently without bottlenecks 3. **πŸ›‘οΈ Enhanced Security**: Distributed control reduces single points of failure 4. **πŸ“ˆ Scalability**: Organizations can grow without centralized management overhead 5. **πŸ”„ Flexible Workflows**: Easy to adapt permissions as teams and projects evolve ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#delegation-hierarchy) Delegation Hierarchy DeDi.global implements a two-tier delegation model: [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#namespace-delegation-apis) Namespace Delegation APIs ----------------------------------------------------------------------------------------------------------------------------------------- Namespace delegation grants administrative access to an entire namespace, allowing delegates to manage all registries within it. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#add-namespace-delegate) Add Namespace Delegate Grant a user administrative access to an entire namespace and all its registries. **Endpoint:** `POST /dedi/{namespace}/add-namespace-delegate` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain **Request Body:** **Prerequisites:** * Requesting user must be the namespace owner or an existing namespace delegate * Target user must have a registered DeDi.global account * Target user cannot already be a namespace delegate **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Missing email, user not found, or user already a delegate * `403` - Insufficient privileges to add delegates * `404` - Namespace not found * `500` - Internal server error **Delegate Permissions:** Once added, namespace delegates can: * Create, update, and manage any registry within the namespace * Add or remove other namespace delegates * View all records across all registries * Export data from any registry * Manage namespace settings and metadata ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#remove-namespace-delegate) Remove Namespace Delegate Remove a user's administrative access from a namespace. **Endpoint:** `POST /dedi/{namespace}/remove-namespace-delegate` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain **Request Body:** **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Missing email or user not found * `403` - Insufficient privileges to remove delegates * `404` - Namespace not found or user not a delegate * `500` - Internal server error **Important Notes:** * Namespace owners cannot remove themselves * Removing a delegate immediately revokes all their namespace-level permissions * Registry-level delegations remain unaffected ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#get-namespace-delegates) Get Namespace Delegates Retrieve a list of all users who have administrative access to a namespace. **Endpoint:** `GET /dedi/{namespace}/get-delegates-by-namespace` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Namespace ID required * `403` - Insufficient privileges to view delegates * `404` - Namespace not found * `500` - Internal server error **Use Cases:** * Audit namespace access permissions * Display administrative team members * Verify delegate assignments for compliance * Monitor access control changes ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#transfer-namespace-ownership) Transfer Namespace Ownership Transfer namespace ownership to another registered user. **Endpoint:** `POST /dedi/{namespace}/transfer-ownership` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain **Request Body:** **Success Response (200):** **Error Responses:** * `400` - Namespace missing, email missing, or token/user lookup failed * `403` - Insufficient privileges to transfer ownership * `404` - Namespace not found or target user not found * `500` - Internal server error **Important Notes:** * The target user must already have a registered DeDi.global account. * The target user email cannot match the current owner email. * The transfer replaces the namespace authorization set with the new owner. * Registry ownership transfer jobs are queued for the namespace's active registries. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#registry-delegation-apis) Registry Delegation APIs --------------------------------------------------------------------------------------------------------------------------------------- Registry delegation grants specific access to individual registries, allowing focused collaboration without broad namespace control. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#add-registry-delegate) Add Registry Delegate Grant a user management access to a specific registry within a namespace. **Endpoint:** `POST /dedi/{namespace}/{registry_name}/add-delegate` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain * `registry_name` (path, required): Registry name to grant access to **Request Body:** **Prerequisites:** * Requesting user must be a namespace delegate or registry owner * Target user must have a registered DeDi.global account * Registry must exist and be accessible **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Missing email, user not found, or user already a delegate * `403` - Insufficient privileges to add delegates * `404` - Namespace or registry not found * `500` - Internal server error **Delegate Permissions:** Registry delegates can: * Create, edit, and delete records within the specific registry * Add or remove other registry delegates (for the same registry) * Modify registry metadata and settings ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#remove-registry-delegate) Remove Registry Delegate Remove a user's access from a specific registry. **Endpoint:** `POST /dedi/{namespace}/{registry_name}/remove-registry-delegate` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain * `registry_name` (path, required): Registry name to remove access from **Request Body:** **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Missing email or user not found * `403` - Insufficient privileges to remove delegates * `404` - Namespace, registry not found, or user not a delegate * `500` - Internal server error **Important Notes:** * Removing a registry delegate only affects access to that specific registry * User may still have namespace-level access if they are a namespace delegate * Registry owners cannot remove themselves ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#get-registry-delegates) Get Registry Delegates Retrieve a list of all users who have access to a specific registry. **Endpoint:** `GET /dedi/{namespace}/{registry_name}/get-delegates-by-registry` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain * `registry_name` (path, required): Registry name to check delegates for **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Missing required parameters * `403` - Insufficient privileges to view delegates * `404` - Namespace or registry not found * `500` - Internal server error **Response Details:** * `**owner**`: Email address of the registry owner * `**delegates**`: Array of delegate email addresses with registry access **Use Cases:** * Audit registry access permissions * Display current team members with registry access * Verify delegate assignments for specific registries * Monitor access control for sensitive data registries [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#best-practices) Best Practices ------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#delegation-strategy) Delegation Strategy 1. **Start with Registry-Level**: Begin with specific registry access and escalate to namespace level only when needed 2. **Regular Audits**: Periodically review delegate lists to ensure appropriate access 3. **Documentation**: Maintain records of why each delegation was granted and when it should be reviewed 4. **Principle of Least Privilege**: Grant minimal necessary permissions for each role ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#security-considerations) Security Considerations 1. **Onboarding/Offboarding**: Promptly add new users and remove those which are no longer needed 2. **Role Changes**: Update delegations when users change roles or departments 3. **Temporary Access**: Consider time-limited approaches for contractors or temporary projects 4. **Monitor Activity**: Track delegate actions for compliance and security monitoring ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#organizational-workflows) Organizational Workflows #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#department-based-structure) **Department-Based Structure:** #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#project-based-structure) **Project-Based Structure:** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#common-use-cases) Common Use Cases 1. **Multi-Department Organizations**: Each department manages their own registries while IT has namespace control 2. **Client Projects**: Project teams get registry access while account managers have namespace oversight 3. **Vendor Collaboration**: External partners get limited registry access for specific deliverables 4. **Compliance Teams**: Auditors and compliance officers get read-only namespace access for monitoring 5. **Development Workflows**: Developers get registry access while DevOps has namespace control for infrastructure Delegation in DeDi.global enables organizations to maintain security while fostering collaboration, ensuring that the right people have the right access to the right data at the right time. [PreviousDomain Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain) [NextUpdate Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update) Last updated 1 month ago Was this helpful? * [Why Delegation Matters in DeDi.global](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#why-delegation-matters-in-dedi.global) * [Organizational Collaboration](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#organizational-collaboration) * [Real-World Scenarios](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#real-world-scenarios) * [Benefits of Delegation](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#benefits-of-delegation) * [Delegation Hierarchy](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#delegation-hierarchy) * [Namespace Delegation APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#namespace-delegation-apis) * [Add Namespace Delegate](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#add-namespace-delegate) * [Remove Namespace Delegate](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#remove-namespace-delegate) * [Get Namespace Delegates](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#get-namespace-delegates) * [Transfer Namespace Ownership](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#transfer-namespace-ownership) * [Registry Delegation APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#registry-delegation-apis) * [Add Registry Delegate](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#add-registry-delegate) * [Remove Registry Delegate](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#remove-registry-delegate) * [Get Registry Delegates](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#get-registry-delegates) * [Best Practices](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#best-practices) * [Delegation Strategy](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#delegation-strategy) * [Security Considerations](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#security-considerations) * [Organizational Workflows](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#organizational-workflows) * [Common Use Cases](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation#common-use-cases) Was this helpful? GitBook AssistantAskCopy Namespace Level (Broad Control) β”œβ”€β”€ Create/manage any registry within the namespace β”œβ”€β”€ Create/manage records within any registry β”œβ”€β”€ Add/remove namespace delegates β”œβ”€β”€ View all registries and records └── Control namespace-wide settings Registry Level (Specific Control) β”œβ”€β”€ Create/edit/delete records within the registry β”œβ”€β”€ Add/remove registry delegates β”œβ”€β”€ Modify registry settings and metadata └── Export registry data GitBook AssistantAskCopy { email: string; // Email address of the user to add as delegate } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/innovatetech-corp/add-namespace-delegate', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ email: '[emailΒ protected]' }) }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Delegate added successfully" } GitBook AssistantAskCopy { email: string; // Email address of the delegate to remove } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/innovatetech-corp/remove-namespace-delegate', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ email: '[emailΒ protected]' }) }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Delegate removed successfully", "current_delegates": [\ "did:web:did.cord.network:3xOwner...",\ "did:web:did.cord.network:3xRemaining..."\ ] } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/innovatetech-corp/get-delegates-by-namespace', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Delegates fetched successfully", "owner": "[emailΒ protected]", "delegates": [\ "[emailΒ protected]",\ "[emailΒ protected]"\ ] } GitBook AssistantAskCopy { email: string; // Email address of the new owner } GitBook AssistantAskCopy { "message": "Namespace transferred successfully", "new_owner": { "email": "[emailΒ protected]", "profile_id": "did:cord:profile:..." } } GitBook AssistantAskCopy { email: string; // Email address of the user to add as delegate } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/innovatetech-corp/employee-profiles/add-delegate', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ email: '[emailΒ protected]' }) }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Delegate added successfully" } GitBook AssistantAskCopy { email: string; // Email address of the delegate to remove } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/innovatetech-corp/employee-profiles/remove-registry-delegate', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ email: '[emailΒ protected]' }) }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Delegate removed successfully", "current_delegates": [\ "did:web:did.cord.network:3xOwner...",\ "did:web:did.cord.network:3xRemaining..."\ ] } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/innovatetech-corp/employee-profiles/get-delegates-by-registry', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Delegates fetched successfully", "owner": "[emailΒ protected]", "delegates": [\ "[emailΒ protected]",\ "[emailΒ protected]"\ ] } GitBook AssistantAskCopy InnovateTech Namespace β”œβ”€β”€ HR Department (Registry Delegates) β”‚ β”œβ”€β”€ employee-profiles β”‚ └── benefits-data β”œβ”€β”€ Engineering (Registry Delegates) β”‚ β”œβ”€β”€ product-specs β”‚ └── development-milestones └── IT Administrators (Namespace Delegates) └── Full access to all registries GitBook AssistantAskCopy ProjectAlpha Namespace β”œβ”€β”€ Core Team (Namespace Delegates) β”‚ └── Full project access β”œβ”€β”€ External Consultants (Registry Delegates) β”‚ β”œβ”€β”€ technical-docs (read-only) β”‚ └── deliverables (write access) └── Stakeholders (Registry Delegates) └── reports (read-only) --- # Update Management | DeDi | NFH Fabric Update Management APIs enable you to modify and evolve your DeDi.global entities after creation while maintaining data integrity and version history. These APIs support controlled updates with immutable versioning, ensuring complete audit trails and rollback capabilities. **Authentication**: πŸ”’ All Update Management APIs require authentication via API key. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#why-updates-matter-in-dedi.global) Why Updates Matter in DeDi.global ----------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#version-control-and-immutability) Version Control and Immutability DeDi.global implements immutable versioning for all updates. When you update any entity, the system: 1. **Preserves History**: Original versions remain unchanged and accessible 2. **Creates New Versions**: Updates generate new version entries with incremented version numbers 3. **Maintains Relationships**: Parent-child relationships and dependencies are preserved 4. **Enables Rollback**: Historical versions can be accessed using version-specific queries ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#real-world-update-scenarios) Real-World Update Scenarios Consider an educational institution "EduTech University" managing student data: #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#namespace-updates) **Namespace Updates** * **Quarterly Rebranding**: Update namespace description and metadata when the university rebrands * **Policy Changes**: Modify TTL values when data retention policies change * **Contact Updates**: Update metadata with new administrative contact information #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#registry-updates) **Registry Updates** * **Schema Evolution**: Change from basic student registry to comprehensive academic records * **Compliance Requirements**: Update metadata to include compliance information * **Department Restructuring**: Modify descriptions when academic departments reorganize #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#record-updates) **Record Updates** * **Student Progress**: Update student records as they complete courses and achieve milestones * **Contact Information**: Modify student contact details when they move or change phone numbers * **Academic Status**: Update enrollment status, GPA, and graduation information * * * [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#namespace-update-apis) Namespace Update APIs ----------------------------------------------------------------------------------------------------------------------------- Namespace updates enable you to modify properties including name, description, metadata, and TTL values while maintaining version history and data integrity. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#update-namespace) Update Namespace Modify an existing namespace with new information while preserving the original version through immutable versioning. **Endpoint:** `POST /dedi/{namespace}/update-namespace` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain **Request Body:** **Prerequisites:** * Requesting user must be a namespace delegate or owner * Either `name` or `description` must be provided * Metadata must follow valid JSON structure **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Missing required fields, empty name, or invalid metadata * `403` - Insufficient privileges to update namespace * `404` - Namespace not found * `500` - Internal server error **Updatable Fields:** Field Updatable Notes βœ… `name` Yes Display name can be changed βœ… `description` Yes Full description updates allowed βœ… `meta` Yes Metadata object can be modified βœ… `ttl` Yes TTL can be adjusted ❌ `namespace_id` No Immutable identifier ❌ `created_by` No Original creator preserved ❌ `genesis` No Creation timestamp preserved ❌ `delegates` No Use delegation APIs instead ❌ `domain` No Use domain verification APIs **Important Notes:** * **Validation Required**: Either `name` or `description` must be provided * **Empty Names Rejected**: Name cannot be empty if provided * **Metadata Validation**: Meta objects must follow valid JSON structure * **Authorization Required**: Only namespace delegates can perform updates * **Version Increment**: Each update creates a new version [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#registry-update-apis) Registry Update APIs --------------------------------------------------------------------------------------------------------------------------- Registry updates allow you to modify properties including description, metadata, schema tags, and TTL values while maintaining schema integrity and state validation. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#update-registry) Update Registry Modify an existing registry while maintaining schema integrity and ensuring proper state validation. **Endpoint:** `POST /dedi/{namespace}/{registry_name}/update-registry` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain * `registry_name` (path, required): Registry name to update **Request Body:** **Prerequisites:** * Requesting user must be a registry delegate or namespace delegate * Registry must be in LIVE state * New schema tags must exist in the bootstrap registry **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Missing required parameters or invalid metadata * `403` - Insufficient privileges to update registry * `404` - Namespace or registry not found, or invalid state * `500` - Internal server error **Updatable Fields:** Field Updatable Notes βœ… `description` Yes Full description updates allowed βœ… `meta` Yes Metadata object can be modified βœ… `tag` Yes Schema tag can be changed (validates against bootstrap registry) βœ… `ttl` Yes TTL can be adjusted ❌ `registry_name` No Immutable identifier ❌ `namespace_id` No Parent namespace cannot be changed ❌ `registry_id` No Unique registry ID preserved ❌ `schema` No Schema structure is immutable (use tag for schema changes) ❌ `created_by` No Original creator preserved ❌ `delegates` No Use delegation APIs instead ❌ `state` No Use state management APIs instead **State Validation:** Registry updates are only allowed for registries in specific states: * βœ… **LIVE**: Full updates permitted * ❌ **INACTIVE**: Updates not allowed **Important Notes:** * **Tag Validation**: New tags must exist in the bootstrap schema registry * **Authorization Required**: Only registry delegates or namespace delegates can perform updates * **State Checks**: Registry must be in LIVE state for updates * **Webhook Notifications**: Updates trigger webhooks to registered watchers [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#record-update-apis) Record Update APIs ----------------------------------------------------------------------------------------------------------------------- Record updates enable you to modify record data, metadata, and validity information with comprehensive schema validation and state management. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#update-record) Update Record Modify existing record data while enforcing schema compliance and maintaining proper state validation. **Endpoint:** `POST /dedi/{namespace}/{registry_name}/{record_name}/update-record` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain * `registry_name` (path, required): Registry name containing the record * `record_name` (path, required): Record name to update **Request Body:** **Prerequisites:** * Requesting user must be a registry delegate or namespace delegate * Record must be in DRAFT or LIVE state * Parent registry must be in LIVE state * Details must conform to registry schema **Example Request:** **Success Responses (200):** For draft records, the response is: **Error Responses:** * `400` - Missing details, schema validation failed, or invalid state * `403` - Insufficient privileges to update record * `404` - Namespace, registry, or record not found * `500` - Internal server error **Updatable Fields:** Field Updatable Notes βœ… `details` Yes Must conform to registry schema βœ… `description` Yes Record description can be updated βœ… `meta` Yes Metadata object can be modified βœ… `valid_till` Yes Expiration date can be adjusted βœ… `ttl` Yes TTL can be modified ❌ `record_name` No Immutable identifier ❌ `record_id` No Unique record ID preserved ❌ `namespace_id` No Parent namespace cannot be changed ❌ `registry_name` No Parent registry cannot be changed ❌ `created_by` No Original creator preserved ❌ `genesis` No Creation timestamp preserved ❌ `state` No Use state management APIs instead **Update Behavior by Record State:** #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#draft-records) Draft Records For records in **DRAFT** state: * **In-Place Updates**: Changes are applied directly to the existing record * **No Version Increment**: Version number remains the same * **No Blockchain Transaction**: Updates are local database operations #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#live-records) Live Records For records in **LIVE** state: * **Version Creation**: New version entry is created * **Blockchain Update**: Changes are recorded on the CORD blockchain * **Immutable History**: Previous version becomes historical * **Strict Schema**: Full schema validation is enforced **State Validation:** Record updates are only allowed for specific states: * βœ… **DRAFT**: Direct updates allowed * βœ… **LIVE**: Versioned updates allowed **Important Notes:** * **Required Field**: `details` must be provided * **Schema Compliance**: Details must match the registry's JSON schema exactly * **Registry State Check**: Parent registry must be in LIVE state * **Authorization Required**: Only registry delegates or namespace delegates can perform updates * **Webhook Notifications**: Updates trigger webhooks to record and registry watchers [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#common-use-cases) Common Use Cases ------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#version-management-strategy) Version Management Strategy 1. **Document Changes**: Use metadata to track update reasons and change details 2. **Incremental Updates**: Make small, focused changes rather than large overwrites 3. **Test Schema Changes**: Validate new tags in development before production updates 4. **Monitor Versions**: Keep track of version counts to understand update frequency ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#data-integrity-guidelines) Data Integrity Guidelines 1. **Schema Validation**: Always validate data against current registry schemas 2. **State Awareness**: Check entity states before attempting updates 3. **Backup Strategy**: Leverage immutable versioning for rollback capabilities 4. **Consistency Checks**: Ensure related records remain consistent across updates ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#organizational-workflows) Organizational Workflows #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#educational-institution-example) **Educational Institution Example:** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#best-practices) Best Practices --------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#update-strategy) Update Strategy 1. **Document Changes**: Use metadata to track update reasons and change details 2. **Incremental Updates**: Make small, focused changes rather than large overwrites 3. **Test Schema Changes**: Validate new tags in development before production updates 4. **Monitor Versions**: Keep track of version counts to understand update frequency ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#security-considerations) Security Considerations 1. **Authorization Verification**: Ensure users have appropriate delegate permissions 2. **State Awareness**: Check entity states before attempting updates 3. **Input Validation**: Validate all input data to prevent injection attacks 4. **Audit Trails**: Use metadata to maintain clear audit trails for compliance ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#performance-optimization) Performance Optimization 1. **Batch Related Updates**: Group related changes into single update operations 2. **TTL Management**: Set appropriate TTL values to balance caching and freshness 3. **Metadata Efficiency**: Keep metadata objects focused and reasonably sized 4. **Update Frequency**: Avoid excessive updates that could impact system performance ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#common-update-workflows) Common Update Workflows 1. **Student Progress Tracking**: Regular GPA and credit updates with semester milestones 2. **Contact Information Management**: Address and phone number updates as users relocate 3. **Schema Evolution**: Gradual migration to new schema versions for enhanced data validation 4. **Compliance Updates**: Metadata changes to reflect new regulatory requirements 5. **Seasonal Updates**: Bulk description and policy updates during annual review periods Update Management APIs in DeDi.global enable organizations to maintain evolving data structures while preserving data integrity, audit trails, and compliance requirements. The immutable versioning system ensures that all changes are tracked and historical data remains accessible for compliance and rollback purposes. [PreviousDelegation Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation) [NextState Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/state-management) Last updated 1 month ago Was this helpful? * [Why Updates Matter in DeDi.global](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#why-updates-matter-in-dedi.global) * [Version Control and Immutability](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#version-control-and-immutability) * [Real-World Update Scenarios](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#real-world-update-scenarios) * [Namespace Update APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#namespace-update-apis) * [Update Namespace](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#update-namespace) * [Registry Update APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#registry-update-apis) * [Update Registry](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#update-registry) * [Record Update APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#record-update-apis) * [Update Record](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#update-record) * [Common Use Cases](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#common-use-cases) * [Version Management Strategy](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#version-management-strategy) * [Data Integrity Guidelines](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#data-integrity-guidelines) * [Organizational Workflows](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#organizational-workflows) * [Best Practices](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#best-practices) * [Update Strategy](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#update-strategy) * [Security Considerations](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#security-considerations) * [Performance Optimization](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#performance-optimization) * [Common Update Workflows](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/update#common-update-workflows) Was this helpful? GitBook AssistantAskCopy { name?: string; // Optional: New namespace display name description?: string; // Optional: Updated description meta?: object; // Optional: Updated metadata object ttl?: number; // Optional: New TTL in seconds } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/edutech-university/update-namespace', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: "EduTech University System", description: "Comprehensive academic data management for EduTech University - Updated for 2024 academic year", meta: { department: "IT Administration", contact: "[emailΒ protected]", updated_reason: "Annual policy review" }, ttl: 31536000 // 1 year in seconds }) }); const data = await response.json(); GitBook AssistantAskCopy { "message": "namespace updated", "data": { "digest": "0x1a2b3c4d5e6f..." } } GitBook AssistantAskCopy { description?: string; // Optional: Updated registry description meta?: object; // Optional: Updated metadata object tag?: string; // Optional: New schema tag reference ttl?: number; // Optional: New TTL in seconds } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/edutech-university/student-records/update-registry', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ description: "Comprehensive student academic records including transcripts, achievements, and enrollment status - Updated for 2024 standards", meta: { data_classification: "confidential", retention_policy: "7_years_post_graduation", last_schema_review: "2024-01-15", department_owner: "registrar" }, tag: "academic-record-v2", ttl: 31536000 }) }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Registry updated", "data": { "digest": "0x2b3c4d5e6f7a..." } } GitBook AssistantAskCopy { details: object; // Required: Updated record data (must match registry schema) description?: string; // Optional: Updated record description meta?: object; // Optional: Updated metadata object valid_till?: string; // Optional: New expiration date (ISO string) ttl?: number; // Optional: New TTL in seconds } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/edutech-university/student-records/john-doe-2024/update-record', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ details: { student_id: "EDU2024001", full_name: "John Michael Doe", email: "[emailΒ protected]", phone: "+1-555-0123", enrollment_status: "active", academic_level: "undergraduate", major: "Computer Science", minor: "Mathematics", gpa: 3.85, credits_completed: 90, expected_graduation: "2025-05-15", address: { street: "123 University Ave", city: "College Town", state: "CA", zip: "90210" }, emergency_contact: { name: "Jane Doe", relationship: "mother", phone: "+1-555-0124" }, last_updated: "2024-02-05T10:30:00Z" }, description: "Updated student record with current academic progress and contact information", meta: { updated_by: "registrar_system", update_reason: "semester_grade_posting", previous_gpa: 3.72, grade_posting_date: "2024-02-01" }, valid_till: "2029-05-15T00:00:00Z", ttl: 126144000 }) }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Record updated", "data": { "digest": "0x3c4d5e6f7a8b..." } } GitBook AssistantAskCopy { "message": "Record edit successful" } GitBook AssistantAskCopy EduTech University Namespace β”œβ”€β”€ Student Records Registry β”‚ β”œβ”€β”€ Update GPAs (Semester-end) β”‚ β”œβ”€β”€ Update contact information (As needed) β”‚ └── Update enrollment status (Registration periods) β”œβ”€β”€ Course Catalog Registry β”‚ β”œβ”€β”€ Update descriptions (Annual review) β”‚ β”œβ”€β”€ Update prerequisites (Curriculum changes) β”‚ └── Update credit hours (Academic policy changes) └── Faculty Directory Registry β”œβ”€β”€ Update office information (As needed) β”œβ”€β”€ Update course assignments (Semester planning) └── Update research interests (Annual updates) --- # Lookup Verification | DeDi | NFH Fabric DeDi.global provides cryptographic verification capabilities that allow you to verify the authenticity and integrity of namespace, registry, and record lookup responses. These APIs enable independent verification of data integrity using the same cryptographic proofs that are anchored on the CORD blockchain. **Authentication**: πŸ”’ All Lookup Verification APIs require authentication via API key. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#what-is-lookup-verification) What is Lookup Verification? ------------------------------------------------------------------------------------------------------------------------------------------------------- Lookup verification is a cryptographic process that allows you to independently verify that the data returned from DeDi.global lookup operations (namespaces, registries, and records) has not been tampered with and originates from the authentic source. This is achieved by recomputing the cryptographic digest of the lookup response data and comparing it against the blockchain-anchored proof. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#why-verification-matters) Why Verification Matters **Data Integrity Assurance:** * Verify that lookup responses haven't been modified in transit * Ensure data authenticity from the original creator * Detect any tampering or corruption of data **Trust Without Intermediaries:** * Independent verification without relying solely on DeDi.global's API * Cryptographic proof validation using the same algorithms as the blockchain * End-to-end data integrity verification **Compliance and Audit:** * Maintain audit trails of verification attempts * Meet regulatory requirements for data integrity * Support legal and compliance frameworks [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#how-verification-works) How Verification Works -------------------------------------------------------------------------------------------------------------------------------------------- The verification process follows the same cryptographic approach used when data is initially anchored on-chain: ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verification-process-flow) Verification Process Flow 1. **Obtain Lookup Response**: Perform a standard namespace, registry, or record lookup 2. **Extract Verification Fields**: Extract specific fields from the response data 3. **Build Verification Object**: Construct an object with the exact fields used for original digest calculation 4. **Canonical Serialization**: Apply the same serialization used during creation 5. **String Conversion**: Convert to string using `JSON.stringify()` 6. **Hash Calculation**: Calculate digest using **BLAKE2 H256** algorithm 7. **Compare Digests**: Compare calculated digest with the digest in the proof section 8. **Log Verification Result**: Store verification attempt and result for audit purposes ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#fields-used-for-digest-calculation) Fields Used for Digest Calculation Each entity type uses specific fields for digest calculation, exactly matching those used during creation: **Namespace Verification Fields:** * `namespace_id` - Unique namespace identifier * `description` - Namespace description * `genesis` - Creation timestamp (ISO string format) * `created_by` - Creator's DID identifier * `version` - Version string * `version_count` - Numeric version counter **Registry Verification Fields:** * `namespace_id` - Parent namespace identifier * `registry_name` - Registry name within namespace * `description` - Registry description * `schema` - JSON schema object * `tag` - Schema tag identifier * `version` - Version string * `version_count` - Numeric version counter * `state` - Registry state (`live` or `inactive`) * `genesis` - Creation timestamp (ISO string format) * `created_by` - Creator's DID identifier * `meta` - Metadata object * `ttl` - Time-to-live value **Record Verification Fields:** * `namespace_id` - Parent namespace identifier * `registry_id` - Parent registry identifier * `registry_name` - Registry name * `record_name` - Record name within registry * `description` - Record description * `details` - Record data content * `version` - Version string * `version_count` - Numeric version counter * `state` - Record state (`draft` or `live`) * `genesis` - Creation timestamp (ISO string format) * `created_by` - Creator's DID identifier * `meta` - Metadata object * `ttl` - Time-to-live value [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#namespace-verification-apis) Namespace Verification APIs ------------------------------------------------------------------------------------------------------------------------------------------------------ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verify-namespace-lookup) Verify Namespace Lookup Cryptographically verify the integrity of a namespace lookup response. **Endpoint:** `POST /dedi/verify-namespace-lookup` **Request Body:** **Example Request:** **Success Response (200):** **Failed Verification (400):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#get-namespace-verification-logs) Get Namespace Verification Logs Retrieve audit trail of namespace verification activities. **Endpoint:** `GET /dedi/{namespace}/get-namespace-verification-logs` **Parameters:** * `namespace` (path, required): Namespace ID or domain to get logs for **Example Request:** **Success Response (200):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#registry-verification-apis) Registry Verification APIs ---------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verify-registry-lookup) Verify Registry Lookup Cryptographically verify the integrity of a registry lookup response. **Endpoint:** `POST /dedi/verify-registry-lookup` **Request Body:** **Example Request:** **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#get-registry-verification-logs) Get Registry Verification Logs Retrieve audit trail of registry verification activities. **Endpoint:** `GET /dedi/{namespace}/{registry_name}/get-registry-verification-logs` **Parameters:** * `namespace` (path, required): Namespace ID or domain * `registry_name` (path, required): Registry name **Example Request:** **Success Response (200):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#record-verification-apis) Record Verification APIs ------------------------------------------------------------------------------------------------------------------------------------------------ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verify-record-lookup) Verify Record Lookup Cryptographically verify the integrity of a record lookup response. **Endpoint:** `POST /dedi/verify-record-lookup` **Request Body:** **Example Request:** **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#get-record-verification-logs) Get Record Verification Logs Retrieve audit trail of record verification activities. **Endpoint:** `GET /dedi/{namespace}/{registry_name}/{record_name}/get-record-verification-logs` **Parameters:** * `namespace` (path, required): Namespace ID or domain * `registry_name` (path, required): Registry name * `record_name` (path, required): Record name **Example Request:** **Success Response (200):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#practical-usage-examples) Practical Usage Examples ------------------------------------------------------------------------------------------------------------------------------------------------ ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verifying-critical-data-before-processing) Verifying Critical Data Before Processing Instead of implementing digest calculation yourself, use DeDi.global's verification APIs to ensure data integrity: #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#academic-record-verification-workflow) Academic Record Verification Workflow #### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#registry-schema-validation-workflow) Registry Schema Validation Workflow ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#audit-trail-and-compliance-monitoring) Audit Trail and Compliance Monitoring ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#real-time-verification-middleware) Real-Time Verification Middleware These examples show how to integrate DeDi.global's verification APIs into your application workflow without needing to implement the complex cryptographic verification logic yourself. The APIs handle all the digest calculation, serialization, and comparison internally, providing you with a simple pass/fail result that you can act upon. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#error-handling) Error Handling ---------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#common-error-responses) Common Error Responses **Missing Lookup Response (400):** **Authentication Required (401):** **User Not Found (404):** **Verification Failed (400):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#best-practices) Best Practices ---------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#security-guidelines) Security Guidelines 1. **Always Verify Responses**: Verify critical lookup responses before trusting the data 2. **Implement Local Verification**: Use client-side verification for additional security 3. **Log Verification Results**: Maintain audit trails of all verification attempts 4. **Handle Verification Failures**: Implement proper error handling for failed verifications 5. **Regular Verification**: Periodically re-verify critical data ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#performance-optimization) Performance Optimization 1. **Cache Verification Results**: Cache verification results for frequently accessed data 2. **Batch Verification**: Verify multiple responses in batch operations when possible 3. **Selective Verification**: Verify only critical data paths based on risk assessment 4. **Background Verification**: Perform verification asynchronously when immediate results aren't required ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#integration-patterns) Integration Patterns 1. **Middleware Integration**: Implement verification as middleware in your application 2. **Webhook Verification**: Verify webhook payloads before processing 3. **API Gateway Integration**: Add verification layers at API gateway level 4. **Event-Driven Verification**: Trigger verification based on specific events or conditions The Lookup Verification APIs provide robust cryptographic verification capabilities, ensuring that data retrieved from DeDi.global maintains its integrity and authenticity throughout your application's data flow. [PreviousSubscription (Watch)](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/subscription) [NextGuides](https://docs.nfh.global/dedi/dedi.global-developers/guides) Last updated 1 month ago Was this helpful? * [What is Lookup Verification?](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#what-is-lookup-verification) * [Why Verification Matters](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#why-verification-matters) * [How Verification Works](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#how-verification-works) * [Verification Process Flow](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verification-process-flow) * [Fields Used for Digest Calculation](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#fields-used-for-digest-calculation) * [Namespace Verification APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#namespace-verification-apis) * [Verify Namespace Lookup](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verify-namespace-lookup) * [Get Namespace Verification Logs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#get-namespace-verification-logs) * [Registry Verification APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#registry-verification-apis) * [Verify Registry Lookup](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verify-registry-lookup) * [Get Registry Verification Logs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#get-registry-verification-logs) * [Record Verification APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#record-verification-apis) * [Verify Record Lookup](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verify-record-lookup) * [Get Record Verification Logs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#get-record-verification-logs) * [Practical Usage Examples](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#practical-usage-examples) * [Verifying Critical Data Before Processing](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#verifying-critical-data-before-processing) * [Audit Trail and Compliance Monitoring](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#audit-trail-and-compliance-monitoring) * [Real-Time Verification Middleware](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#real-time-verification-middleware) * [Error Handling](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#error-handling) * [Common Error Responses](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#common-error-responses) * [Best Practices](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#best-practices) * [Security Guidelines](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#security-guidelines) * [Performance Optimization](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#performance-optimization) * [Integration Patterns](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/lookup-verification#integration-patterns) Was this helpful? GitBook AssistantAskCopy { "namespace_lookup_response": { "message": "string", "data": { "namespace_id": "string", "description": "string", "genesis": "string (ISO timestamp)", "created_by": "string", "version": "string", "version_count": "number", "proof": { "type": "string", "namespace_did": "string", "creator_did": "string", "digest": "string (hex)", "network_genesis": "string (hex)" } } } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/verify-namespace-lookup', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-key' }, body: JSON.stringify({ namespace_lookup_response: namespaceResponse }) }); const verificationResult = await response.json(); GitBook AssistantAskCopy { "message": "Verification successful" } GitBook AssistantAskCopy { "message": "Verification failed" } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/acme-university/get-namespace-verification-logs', { method: 'GET', headers: { 'Authorization': 'Bearer your-api-key' } }); const logs = await response.json(); GitBook AssistantAskCopy { "message": "Verification logs fetched successfully", "data": { "verification_count": 5, "logs": [\ {\ "id": "vt_62...",\ "lookup_type": "namespace",\ "verified_id": "76EU...",\ "verified_by": "[emailΒ protected]",\ "result": "success",\ "created_at": "2024-01-15T14:30:00Z",\ "request": {\ "message": "Resource retrieved successfully",\ "data": { "..." }\ }\ },\ ...\ ] } } GitBook AssistantAskCopy { "registry_lookup_response": { "message": "string", "data": { "namespace_id": "string", "registry_id": "string", "registry_name": "string", "description": "string", "schema": "object (JSON schema)", "tag": "string", "version": "string", "version_count": "number", "state": "string", "genesis": "string (ISO timestamp)", "created_by": "string", "meta": "object", "ttl": "number", "proof": { "type": "string", "namespace_did": "string", "registry_identifier": "string", "creator_did": "string", "digest": "string (hex)", "network_genesis": "string (hex)" } } } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/verify-registry-lookup', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-key' }, body: JSON.stringify({ registry_lookup_response: registryResponse }) }); const verificationResult = await response.json(); GitBook AssistantAskCopy { "message": "Verification successful" } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/acme-university/student-records/get-registry-verification-logs', { method: 'GET', headers: { 'Authorization': 'Bearer your-api-key' } }); const logs = await response.json(); GitBook AssistantAskCopy { "message": "Verification logs fetched successfully", "data": { "verification_count": 3, "logs": [\ {\ "id": "vt_62...",\ "lookup_type": "registry",\ "verified_id": "76EU...",\ "verified_by": "[emailΒ protected]",\ "result": "success",\ "created_at": "2024-01-15T15:45:00Z",\ "request": {\ "message": "Resource retrieved successfully",\ "data": { "..." }\ }\ },\ ...\ ] } } GitBook AssistantAskCopy { "record_lookup_response": { "message": "string", "data": { "namespace_id": "string", "registry_id": "string", "registry_name": "string", "record_id": "string", "record_name": "string", "description": "string", "details": "object (record data)", "version": "string", "version_count": "number", "state": "string", "genesis": "string (ISO timestamp)", "created_by": "string", "meta": "object", "ttl": "number", "proof": { "type": "string", "namespace_did": "string", "registry_identifier": "string", "record_identifier": "string", "creator_did": "string", "digest": "string (hex)", "network_genesis": "string (hex)" } } } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/verify-record-lookup', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-key' }, body: JSON.stringify({ record_lookup_response: recordResponse }) }); const verificationResult = await response.json(); GitBook AssistantAskCopy { "message": "Verification successful" } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/acme-university/student-records/john-doe-2024/get-record-verification-logs', { method: 'GET', headers: { 'Authorization': 'Bearer your-api-key' } }); const logs = await response.json(); GitBook AssistantAskCopy { "message": "Verification logs fetched successfully", "data": { "verification_count": 7, "logs": [\ {\ "id": "vt_62...",\ "lookup_type": "record",\ "verified_id": "76EU...",\ "verified_by": "[emailΒ protected]",\ "result": "success",\ "created_at": "2024-01-15T16:20:00Z",\ "request": {\ "message": "Resource retrieved successfully",\ "data": { "..." }\ }\ },\ ...\ ] } } GitBook AssistantAskCopy // Step 1: Perform a standard record lookup async function getStudentRecord(namespace: string, registry: string, recordName: string) { const lookupResponse = await fetch(`https://api.dedi.global/dedi/lookup/${namespace}/${registry}/${recordName}`, { headers: { 'Authorization': 'Bearer your-api-key' } }); return await lookupResponse.json(); } // Step 2: Verify the lookup response before trusting the data async function verifyAndProcessRecord(namespace: string, registry: string, recordName: string) { try { // Get the record data const recordLookup = await getStudentRecord(namespace, registry, recordName); // Verify the data integrity using DeDi.global's verification API const verificationResponse = await fetch('https://api.dedi.global/dedi/verify-record-lookup', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-key' }, body: JSON.stringify({ record_lookup_response: recordLookup }) }); const verificationResult = await verificationResponse.json(); if (verificationResponse.ok) { console.log('βœ“ Record verified successfully'); // Process the verified data processStudentRecord(recordLookup.data); } else { console.error('βœ— Verification failed:', verificationResult.message); // Handle verification failure handleVerificationFailure(recordLookup); } } catch (error) { console.error('Error in verification workflow:', error); } } function processStudentRecord(recordData: any) { // Now you can safely process the verified data console.log('Processing verified student record:', recordData.record_name); // Your business logic here... } function handleVerificationFailure(recordData: any) { // Log the failure and take appropriate action console.warn('Data integrity check failed for record:', recordData.data?.record_name); // Maybe retry, notify administrators, or reject the data } GitBook AssistantAskCopy // Verify registry before creating records async function safeRegistryOperations(namespace: string, registryName: string) { try { // Look up the registry const registryResponse = await fetch(`https://api.dedi.global/dedi/lookup/${namespace}/${registryName}`, { headers: { 'Authorization': 'Bearer your-api-key' } }); const registryLookup = await registryResponse.json(); // Verify registry integrity const verificationResponse = await fetch('https://api.dedi.global/dedi/verify-registry-lookup', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-key' }, body: JSON.stringify({ registry_lookup_response: registryLookup }) }); if (verificationResponse.ok) { console.log('βœ“ Registry schema verified'); return registryLookup.data.schema; // Safe to use the schema } else { throw new Error('Registry verification failed'); } } catch (error) { console.error('Registry verification error:', error); return null; } } GitBook AssistantAskCopy // Monitor verification activities for compliance async function auditVerificationActivity(namespace: string) { try { // Get namespace verification logs const logsResponse = await fetch(`https://api.dedi.global/dedi/${namespace}/get-namespace-verification-logs`, { headers: { 'Authorization': 'Bearer your-api-key' } }); const logs = await logsResponse.json(); console.log(`Found ${logs.data.verification_count} verification attempts`); // Analyze verification patterns const failedVerifications = logs.data.logs.filter(log => log.result === 'failed'); if (failedVerifications.length > 0) { console.warn(`⚠️ ${failedVerifications.length} failed verification attempts detected`); // Alert security team or take corrective action } return logs.data; } catch (error) { console.error('Audit retrieval error:', error); } } GitBook AssistantAskCopy // Express.js middleware for automatic verification function verificationMiddleware(entityType: 'namespace' | 'registry' | 'record') { return async (req: any, res: any, next: any) => { const lookupResponse = res.locals.lookupData; // Assume lookup data is stored here if (!lookupResponse) { return next(); } try { const verifyEndpoint = `https://api.dedi.global/dedi/verify-${entityType}-lookup`; const requestBody = { [`${entityType}_lookup_response`]: lookupResponse }; const verificationResponse = await fetch(verifyEndpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-api-key' }, body: JSON.stringify(requestBody) }); if (verificationResponse.ok) { res.locals.verified = true; console.log(`βœ“ ${entityType} verification passed`); } else { res.locals.verified = false; console.warn(`βœ— ${entityType} verification failed`); } } catch (error) { console.error('Verification middleware error:', error); res.locals.verified = false; } next(); }; } // Usage in routes app.get('/api/student/:recordName', lookupRecord, // First get the data verificationMiddleware('record'), // Then verify it (req, res) => { if (res.locals.verified) { res.json(res.locals.lookupData); } else { res.status(400).json({ error: 'Data verification failed' }); } } ); GitBook AssistantAskCopy { "message": "Invalid input: namespace_lookup_response is missing" } GitBook AssistantAskCopy { "message": "Authentication failed" } GitBook AssistantAskCopy { "message": "User not found" } GitBook AssistantAskCopy { "message": "Verification failed" } --- # How are DeDi.global entries cryptographically secured? | DeDi | NFH Fabric DeDi.global entries are cryptographically secured through proof anchoring on the CORD blockchain. Proofs are anchored at **every level** of the hierarchyβ€”namespaces, registries, and records each have their own cryptographic proof. ### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#how-proofs-work) How Proofs Work Every entry in DeDi is secured through a consistent process: 1. The entry data is converted into an object 2. Canonically serialized 3. Stringified using `JSON.stringify()` 4. Hashed using **BLAKE2 H256** The resulting digest, along with metadata about the creator and network, forms the proof that is anchored on-chain. ### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#proof-structures) Proof Structures #### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#namespace-proof) Namespace Proof GitBook AssistantAskCopy { "type": "DediNamespaceProof2025", "namespace_did": "did:dedi:namespace:acme-org", "creator_did": "did:web:acme.org#admin", "digest": "0x8f3c91a2b7d4e918c0d55eab3c1a9e4e21e9f8c3d7c6b1a2f4c9d88e1a7b3f22", "network_genesis": "0x93abf42c1d77e8f0a928f31fd29d77bd73cd91eb99f15e41f6d39e087ac3b22c" } **Fields used for digest calculation:** `namespace_id`, `description`, `genesis`, `created_by`, `version`, `version_count` #### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#registry-proof) Registry Proof **Fields used for digest calculation:** `namespace_id`, `registry_name`, `description`, `schema`, `tag`, `version`, `version_count`, `state`, `genesis`, `created_by`, `meta`, `ttl` #### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#record-proof) Record Proof **Fields used for digest calculation:** `namespace_id`, `registry_id`, `registry_name`, `record_name`, `description`, `details`, `version`, `version_count`, `state`, `genesis`, `created_by`, `meta`, `ttl` ### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#how-verification-works) How Verification Works To verify any DeDi entry (namespace, registry, or record): 1. **Lookup** β€” Query the entry via DeDi API 2. **Extract fields** β€” Take the fields required for digest calculation from the response 3. **Build object** β€” Convert extracted fields into an object 4. **Serialize** β€” Apply canonical serialization 5. **Stringify** β€” Convert to string using `JSON.stringify()` 6. **Hash** β€” Calculate digest using BLAKE2 H256 7. **Compare** β€” Verify that your calculated digest matches the `digest` in the proof #### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#on-chain-verification) On-Chain Verification For additional assurance, verify directly against the CORD blockchain: 1. Go to [apps.cord.network](https://apps.cord.network/) (CORD explorer) 2. Perform a state query using the entry's identifier (`namespace_id`, `registry_id`, or `record_id`) 3. The returned digest should match what you calculated This confirms the proof was genuinely anchored on-chain and hasn't been tampered with. ### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#did-documents) DID Documents For every `profile_id`, a DID document is automatically generated: Access any DID document at: `https://did.cord.network/{id}/did.json` ### [](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#summary) Summary Level Proof Type Key Identifiers **Namespace** `DediNamespaceProof2025` `namespace_did`, `creator_did` **Registry** `DeDiRegistryProof2025` `namespace_did`, `registry_identifier`, `creator_did` **Record** `DediRecordProof2025` `namespace_did`, `registry_identifier`, `record_identifier`, `creator_did` All proofs include a `digest` (BLAKE2 H256 hash of entry data) and `network_genesis` (CORD chain identifier), and can be independently verified both through the DeDi API and directly on-chain. [PreviousDeDi in Verifiable Credential Workflows](https://docs.nfh.global/dedi/resources/dedi-in-verifiable-credential-workflows) [NextDeveloper documentation](https://docs.nfh.global/dedi/dedi.global-developers/developer-documentation) Last updated 1 month ago Was this helpful? * [How Proofs Work](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#how-proofs-work) * [Proof Structures](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#proof-structures) * [How Verification Works](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#how-verification-works) * [DID Documents](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#did-documents) * [Summary](https://docs.nfh.global/dedi/resources/how-are-dedi.global-entries-cryptographically-secured#summary) Was this helpful? GitBook AssistantAskCopy { "type": "DeDiRegistryProof2025", "namespace_did": "did:dedi:ns:acme.global", "registry_identifier": "registry:acme.membership", "creator_did": "did:web:acme.org#admin", "digest": "0x91ef3ab2c77dd9f01892bf31cd29b8ae7f5dd321ee019ec45bd119ab4cf72d11", "network_genesis": "0x93abf42c1d77e8f0a928f31fd29d77bd73cd91eb99f15e41f6d39e087ac3b22c" } GitBook AssistantAskCopy { "type": "DediRecordProof2025", "namespace_did": "did:dedi:ns:acme.global", "registry_identifier": "registry:acme.membership", "record_identifier": "record:acme.membership.member123", "creator_did": "did:web:acme.org#issuer1", "digest": "0xa17cd92be81f7c0da923ff10efa92b9b37cd10aa8e1c4ff2342dd19cbf9023af", "network_genesis": "0x93abf42c1d77e8f0a928f31fd29d77bd73cd91eb99f15e41f6d39e087ac3b22c" } GitBook AssistantAskCopy did:web:did.cord.network:{id} --- # Access APIs | DeDi | NFH Fabric The Access APIs provide comprehensive data retrieval capabilities for the DeDi.global platform. These read-oriented endpoints allow you to look up, query, and explore namespaces, registries, and records with filtering and version management support. 🌐 **Public Read Access**: Lookup, query, version, and search endpoints are available without mandatory authentication. You may still send an API key when your integration standardizes authenticated requests. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#overview) Overview --------------------------------------------------------------------------------------------------- Access APIs are organized into three main categories: * **Lookup APIs** - Retrieve detailed information about specific resources * **Query APIs** - Search and filter collections of resources with pagination * **Version APIs** - Manage and retrieve historical versions of resources These access APIs support both current and historical data queries. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#lookup-apis) Lookup APIs --------------------------------------------------------------------------------------------------------- Lookup APIs provide detailed information about specific resources using their identifiers. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#namespace-lookup) Namespace Lookup Retrieve detailed information about a specific namespace. **Endpoint:** `GET /dedi/lookup/{namespace}` **Parameters:** * `namespace` (path, required): Namespace ID or verified domain * `version_id` (query, optional): Specific version to retrieve * `as_on` (query, optional): Historical lookup date (YYYY-MM-DD format) **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Invalid namespace parameter or date format * `404` - Namespace not found or version not found * `500` - Internal server error ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#registry-lookup) Registry Lookup Retrieve detailed information about a specific registry. **Endpoint:** `GET /dedi/lookup/{namespace}/{registry_name}` **Parameters:** * `namespace` (path, required): Namespace ID or domain * `registry_name` (path, required): Registry name * `version_id` (query, optional): Specific version to retrieve * `as_on` (query, optional): Historical lookup date (YYYY-MM-DD format) **Example Request:** **Success Response (200):** > **Important**: A `200` response indicates successful data retrieval, not that the registry is active. Always check the `state` field to verify the registry's current status before using it. **Error Responses:** * `400` - Missing namespace or registry name * `404` - Namespace or registry not found * `500` - Internal server error ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#record-lookup) Record Lookup Retrieve detailed information about a specific record. **Endpoint:** `GET /dedi/lookup/{namespace}/{registry_name}/{record_name}` **Parameters:** * `namespace` (path, required): Namespace ID or domain * `registry_name` (path, required): Registry name * `record_name` (path, required): Record name * `version_id` (query, optional): Specific version to retrieve * `as_on` (query, optional): Historical lookup date (YYYY-MM-DD format) **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Missing required parameters * `404` - Namespace, registry, or record not found * `500` - Internal server error [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-apis) Query APIs ------------------------------------------------------------------------------------------------------- Query APIs enable searching and filtering collections with pagination support. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-registries-by-namespace) Query Registries by Namespace List all registries within a namespace with filtering options. **Endpoint:** `GET /dedi/query/{namespace}` **Parameters:** * `namespace` (path, required): Namespace ID or domain * `from` (query, optional): Filter from date (YYYY-MM-DD) * `to` (query, optional): Filter to date (YYYY-MM-DD) * `status` (query, optional): Filter by status (`active`, `inactive`) * `name` (query, optional): Search by registry name (minimum 3 characters) * `sort` (query, optional): Sort by `date`, `status`, `name`, or `id` * `page` (query, optional): Page number for pagination * `page_size` (query, optional): Items per page * `as_on` (query, optional): Historical query date (YYYY-MM-DD) **Example Request:** **Success Response (200):** **Error Responses:** * `404` - Namespace not found * `500` - Internal server error ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-records-by-registry) Query Records by Registry List all records within a registry with filtering options. **Endpoint:** `GET /dedi/query/{namespace}/{registry_name}` **Parameters:** * `namespace` (path, required): Namespace ID or domain * `registry_name` (path, required): Registry name * `from` (query, optional): Filter from date (YYYY-MM-DD) * `to` (query, optional): Filter to date (YYYY-MM-DD) * `state` (query, optional): Filter by state (`live`) * `name` (query, optional): Search by record name (minimum 3 characters) * `sort` (query, optional): Sort by `date`, `status`, `name`, or `id` * `page` (query, optional): Page number for pagination * `page_size` (query, optional): Items per page * `as_on` (query, optional): Historical query date (YYYY-MM-DD) **Example Request:** **Success Response (200):** **Error Responses:** * `404` - Registry or namespace not found * `500` - Internal server error ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-registries-by-schema-tag) Query Registries by Schema Tag Find verified registries by their schema tag across the platform. **Endpoint:** `GET /dedi/{tag}/get-registry-by-tag` **Parameters:** * `tag` (path, required): Schema tag to filter by (e.g., `membership`, `public_key`, `revoke`) > **Note:** The tag cannot be `custom` as this endpoint is specifically for standardized schemas. **Authentication:** Not required **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Invalid tag (cannot be 'custom' or missing) * `500` - Internal server error [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#version-apis) Version APIs ----------------------------------------------------------------------------------------------------------- Version APIs provide access to historical versions and evolution tracking for all resources. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#namespace-versions) Namespace Versions Retrieve all available versions for a namespace. **Endpoint:** `GET /dedi/versions/{namespace}` **Parameters:** * `namespace` (path, required): Namespace ID or domain **Example Request:** **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#registry-versions) Registry Versions Retrieve all available versions for a registry. **Endpoint:** `GET /dedi/versions/{namespace}/{registry_name}` **Parameters:** * `namespace` (path, required): Namespace ID or domain * `registry_name` (path, required): Registry name **Example Request:** **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#record-versions) Record Versions Retrieve all available versions for a record. **Endpoint:** `GET /dedi/versions/{namespace}/{registry_name}/{record_name}` **Parameters:** * `namespace` (path, required): Namespace ID or domain * `registry_name` (path, required): Registry name * `record_name` (path, required): Record name **Example Request:** **Success Response (200):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#error-handling) Error Handling --------------------------------------------------------------------------------------------------------------- All Access APIs follow consistent error response patterns: ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#common-error-responses) Common Error Responses **400 Bad Request:** **401 Unauthorized:** **404 Not Found:** **500 Internal Server Error:** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#best-practices) Best Practices --------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#performance-optimization) Performance Optimization 1. **Use specific lookups** when you know exact resource identifiers 2. **Implement pagination** for large result sets 3. **Cache frequently accessed** namespace and registry data 4. **Use historical queries sparingly** as they are more resource-intensive ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-efficiency) Query Efficiency 1. **Apply filters** to reduce result set size 2. **Use date ranges** for time-based queries 3. **Sort consistently** to improve cache performance 4. **Implement client-side caching** for static data ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#version-management) Version Management 1. **Track version counts** to detect updates 2. **Use version\_id** for reproducible results 3. **Cache version lists** as they change infrequently 4. **Implement version-aware** client logic [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#examples-and-use-cases) Examples and Use Cases ------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#real-time-data-synchronization) Real-time Data Synchronization ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#advanced-search-implementation) Advanced Search Implementation ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#historical-analysis) Historical Analysis [PreviousPublish APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish) [NextDomain Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain) Last updated 1 month ago Was this helpful? * [Overview](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#overview) * [Lookup APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#lookup-apis) * [Namespace Lookup](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#namespace-lookup) * [Registry Lookup](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#registry-lookup) * [Record Lookup](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#record-lookup) * [Query APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-apis) * [Query Registries by Namespace](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-registries-by-namespace) * [Query Records by Registry](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-records-by-registry) * [Query Registries by Schema Tag](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-registries-by-schema-tag) * [Version APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#version-apis) * [Namespace Versions](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#namespace-versions) * [Registry Versions](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#registry-versions) * [Record Versions](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#record-versions) * [Error Handling](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#error-handling) * [Common Error Responses](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#common-error-responses) * [Best Practices](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#best-practices) * [Performance Optimization](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#performance-optimization) * [Query Efficiency](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#query-efficiency) * [Version Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#version-management) * [Examples and Use Cases](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#examples-and-use-cases) * [Real-time Data Synchronization](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#real-time-data-synchronization) * [Advanced Search Implementation](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#advanced-search-implementation) * [Historical Analysis](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access#historical-analysis) Was this helpful? GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/lookup/my-namespace', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Namespace details retrieved successfully", "data": { "domain": "example.com", "name": "my-namespace", "namespace_id": "did:cord:3yVazTQMc...", "digest": "0x123abc...", "description": "Production namespace for example.com services", "created_by": "did:cord:3xMxFkzY...", "genesis": "0x456def...", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "version": "0x789ghi...", "version_count": 3, "is_verified": true, "meta": { "category": "production", "region": "global" }, "registry_count": 15, "ttl": 86400, "proof": { "type": "DediNamespaceProof2026", "namespace_did": "did:cord:3yVazTQMc...", "creator_did": "did:cord:3xMxFkzY...", "digest": "0x123abc...", "network_genesis": "0x101112..." } } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/lookup/my-namespace/user-registry', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Resource retrieved successfully", "data": { "namespace": "my-namespace", "namespace_id": "did:cord:3yVazTQMc...", "registry_id": "did:cord:3zAbcDef...", "registry_name": "user-registry", "digest": "0x456abc...", "description": "User management registry for authentication", "created_by": "did:cord:3xMxFkzY...", "tag": "membership", "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["admin", "user"] }, "active": { "type": "boolean" } }, "required": ["email", "role"] }, "genesis": "0x789def...", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "state": "live", "meta": { "department": "engineering", "priority": "high" }, "record_count": 150, "version_count": 2, "version": "0x012ghi...", "query_allowed": true, "ttl": 3600, "proof": { "type": "DediRegistryProof2026", "namespace_did": "did:cord:3yVazTQMc...", "registry_identifier": "did:cord:3zAbcDef...", "creator_did": "did:cord:3xMxFkzY...", "digest": "0x456abc...", "network_genesis": "0x101112..." } } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/lookup/my-namespace/user-registry/john-doe', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Resource retrieved successfully", "data": { "namespace": "my-namespace", "namespace_id": "did:cord:3yVazTQMc...", "registry_id": "did:cord:3zAbcDef...", "registry_name": "user-registry", "registry_state": "live", "record_id": "did:cord:3aRecDef...", "record_name": "john-doe", "description": "User record for John Doe", "digest": "0x789abc...", "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["admin", "user"] } } }, "version_count": 3, "version": "0x345ghi...", "details": { "email": "[emailΒ protected]", "role": "admin", "active": true, "last_login": "2024-01-01T10:30:00Z" }, "meta": { "department": "engineering", "access_level": "high" }, "genesis": "2024-01-01T00:00:00.000Z", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "created_by": "did:cord:3xMxFkzY...", "state": "live", "ttl": 86400, "proof": { "type": "DediRecordProof2026", "namespace_did": "did:cord:3yVazTQMc...", "registry_identifier": "did:cord:3zAbcDef...", "record_identifier": "did:cord:3aRecDef...", "creator_did": "did:cord:3xMxFkzY...", "digest": "0x789abc...", "network_genesis": "0x101112..." } } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/query/my-namespace?sort=date&page=1&page_size=10', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Resource retrieved successfully", "data": { "namespace_id": "did:cord:3yVazTQMc...", "namespace_name": "my-namespace", "domain": "my-namespace.dedi.global", "created_by": "did:cord:3xMxFkzY...", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "total_registries": 25, "page_number": 1, "page_size": 10, "registries": [\ {\ "registry_id": "did:cord:3zAbcDef...",\ "registry_name": "user-registry",\ "description": "Registry for user profiles",\ "digest": "0x456def...",\ "tag": "users",\ "schema": {\ "type": "object",\ "properties": {\ "email": { "type": "string", "format": "email" }\ }\ },\ "genesis": "2024-01-01T00:00:00.000Z",\ "created_at": "2024-01-01T00:00:00Z",\ "updated_at": "2024-01-01T00:00:00Z",\ "created_by": "did:cord:3xMxFkzY...",\ "state": "live",\ "meta": {\ "category": "identity",\ "version": "v1.0"\ },\ "record_count": 150,\ "version_count": 3,\ "version": "0x789abc...",\ "query_allowed": true,\ "ttl": 86400\ }\ ] } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/query/my-namespace/user-registry?state=live&sort=name', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Resource retrieved successfully", "data": { "namespace_id": "did:cord:3yVazTQMc...", "namespace_name": "my-namespace", "registry_name": "user-registry", "registry_id": "did:cord:3zAbcDef...", "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["admin", "user"] } } }, "meta": { "category": "identity", "access_level": "public" }, "created_by": "did:cord:3xMxFkzY...", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "total_records": 150, "total_pages": 15, "page_number": 1, "page_size": 10, "records": [\ {\ "record_id": "did:cord:3aRecDef...",\ "record_name": "john-doe",\ "description": "User record for John Doe",\ "digest": "0x789abc...",\ "details": {\ "email": "[emailΒ protected]",\ "role": "admin",\ "active": true\ },\ "genesis": "2024-01-01T00:00:00.000Z",\ "created_at": "2024-01-01T00:00:00Z",\ "updated_at": "2024-01-01T00:00:00Z",\ "created_by": "did:cord:3xMxFkzY...",\ "state": "live",\ "version_count": 2,\ "version": "0x345ghi...",\ "ttl": 86400,\ "meta": {\ "department": "engineering",\ "access_level": "high"\ }\ }\ ] } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/membership/get-registry-by-tag', { method: 'GET' }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Resource retrieved successfully", "data": { "tag": "membership", "total_registries": 1, "registries": [\ {\ "registry_id": "did:cord:3zAbcDef...",\ "registry_name": "employee-registry",\ "namespace_id": "did:cord:3yVazTQMc...",\ "description": "Employee membership registry",\ "digest": "0x456def...",\ "tag": "membership",\ "schema": {\ "type": "object",\ "properties": {\ "email": { "type": "string", "format": "email" },\ "role": { "type": "string" },\ "department": { "type": "string" }\ }\ },\ "genesis": "2024-01-01T00:00:00.000Z",\ "created_at": "2024-01-01T00:00:00Z",\ "updated_at": "2024-01-01T00:00:00Z",\ "created_by": "did:cord:3xMxFkzY...",\ "state": "live",\ "meta": {\ "category": "membership",\ "version": "v2.0"\ },\ "record_count": 50,\ "version_count": 3,\ "version": "0x789abc...",\ "query_allowed": true,\ "ttl": 86400\ }\ ] } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/versions/my-namespace', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Resource retrieved successfully", "data": { "created_by": "did:cord:3xMxFkzY...", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "total_versions": 5, "versions": [\ "0x789ghi...", // Latest\ "0x456def...",\ "0x123abc...", // Oldest\ ], "ttl": 86400 } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/versions/my-namespace/user-registry', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Resource retrieved successfully", "data": { "registry_name": "user-registry", "created_by": "did:cord:3xMxFkzY...", "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string" } } }, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "total_versions": 3, "versions": [\ "0x345ghi...", // Latest\ "0x012def...",\ "0x789abc..." // Oldest\ ], "ttl": 3600 } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/versions/my-namespace/user-registry/john-doe', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Resource retrieved successfully", "data": { "created_by": "did:cord:3xMxFkzY...", "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string" } } }, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", "total_versions": 4, "versions": [\ "0x567jkl...", // Latest\ "0x345ghi...",\ "0x123def...",\ "0x901abc..." // Oldest\ ], "ttl": 86400 } } GitBook AssistantAskCopy { "message": "Invalid input: namespace is missing or empty" } GitBook AssistantAskCopy { "message": "Unauthorized: Invalid or missing authentication token" } GitBook AssistantAskCopy { "message": "Namespace not found" } GitBook AssistantAskCopy { "message": "An unexpected error occurred" } GitBook AssistantAskCopy // Check for updates and sync data async function syncNamespaceData(namespaceId: string) { const current = await lookup.namespace(namespaceId); const cached = getCachedVersion(namespaceId); if (current.version_count > cached.version_count) { // Fetch and cache updated data await updateCache(namespaceId, current); // Sync registries if needed const registries = await query.registriesByNamespace(namespaceId); await syncRegistries(registries.data.registries); } } GitBook AssistantAskCopy // Multi-criteria registry search async function searchRegistries(criteria: SearchCriteria) { const results = await query.registriesByNamespace(criteria.namespace, { from: criteria.dateRange.start, to: criteria.dateRange.end, name: criteria.searchTerm, sort: 'date', page: criteria.page, page_size: 20 }); // Filter by tag if specified if (criteria.schemaTag) { const taggedRegistries = await query.registriesByTag(criteria.schemaTag); return filterAndMerge(results.data, taggedRegistries.data); } return results.data; } GitBook AssistantAskCopy // Analyze resource evolution over time async function analyzeResourceHistory(namespace: string, registry: string) { const versions = await version.registry(namespace, registry); const analysis = { totalVersions: versions.data.total_versions, evolutionTimeline: [], schemaChanges: [] }; // Fetch each version for comparison for (const versionId of versions.data.versions) { const versionData = await lookup.registry(namespace, registry, { version_id: versionId }); analysis.evolutionTimeline.push({ version: versionId, timestamp: versionData.data.updated_at, changes: compareSchemas(versionData.data.schema) }); } return analysis; } --- # Domain Verification | DeDi | NFH Fabric Domain verification is a critical trust mechanism that enhances the credibility and authenticity of namespaces on DeDi.global. By proving ownership of a domain, organizations can establish verified namespaces that users can trust. **Authentication**: πŸ”’ All Domain Verification APIs require authentication via API key. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#why-domain-verification-matters) Why Domain Verification Matters ------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#trust-through-domain-ownership) Trust Through Domain Ownership Domains are the fundamental source of identity on the internet. They represent a unique, globally recognized identifier that only the legitimate owner can control. The internet's trust infrastructure is built around domain ownership - when you visit `microsoft.com`, you trust that Microsoft Corporation owns and controls that domain. DeDi.global leverages this established trust mechanism to bring the same level of confidence to decentralized data. By allowing namespace owners to attach verified domains to their namespaces, we create a bridge between traditional web trust and decentralized identity. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#the-verification-advantage) The Verification Advantage Consider a scenario where multiple organizations create namespaces with similar names like "TechCorp", "TechCorp-Official", or "TechCorp-Inc". Without domain verification, users have no reliable way to distinguish between legitimate and potentially fraudulent namespaces. However, when the legitimate TechCorp organization verifies their namespace using their domain `techcorp.com`, they gain: * **🎯 Authentic Identity**: Clear proof of legitimacy through domain ownership * **⭐ Enhanced Trust**: Verified status increases user confidence and adoption * **πŸ›‘οΈ Brand Protection**: Differentiation from potentially misleading similar namespaces * **πŸ“ˆ Better Discovery**: Verified namespaces receive priority in search and recommendations ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#real-world-example) Real-World Example Imagine three namespaces exist: * `global-bank` (unverified) * `globalbank-official` (unverified) * `global-bank-verified` (verified with `globalbank.com`) Users interacting with financial data would naturally trust the domain-verified namespace, knowing that only the real Global Bank can control the `globalbank.com` domain. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#how-domain-verification-works) How Domain Verification Works --------------------------------------------------------------------------------------------------------------------------------------------- The verification process follows a secure, industry-standard DNS-based validation: ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-1.-namespace-creation) 1\. **Namespace Creation** First, create your namespace using the [Create Namespace API](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#create-namespace) : ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-2.-choose-a-verification-method) 2\. **Choose a Verification Method** DeDi.global supports three verification flows: * `self_dns` - prove ownership by publishing the TXT value in DNS * `self_http` - prove ownership by serving the TXT value from `https:///.well-known/dedi-verification.txt` * `request_other_namespace` - request an already self-verified namespace to attest your domain For the self-managed flows (`self_dns` and `self_http`), the domain must still be present in the DeDi.global global registry. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-3.-domain-whitelisting-global-registry-check) 3\. **Domain Whitelisting / Global Registry Check** Before generating self-managed verification records, your domain must be available in the DeDi.global global registry: > **πŸ“ž Contact Required**: To get your domain whitelisted for verification, please reach out to the DeDi.global team through our support channels. This security measure prevents abuse and ensures domain legitimacy. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-4.-verification-record-generation) 4\. **Verification Record Generation** Generate a unique verification string using the [Generate DNS TXT API](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#generate-dns-txt-record) : ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-5.-publish-the-proof) 5\. **Publish the Proof** For `self_dns`, add the generated TXT record to your domain's DNS settings through your domain provider (GoDaddy, Cloudflare, Route 53, etc.): For `self_http`, expose the same TXT value at: For `request_other_namespace`, the generate step creates a pending request for the target namespace delegates. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-6.-verification) 6\. **Verification** Once DNS propagation is complete (usually 5-30 minutes), verify your domain using the [Verify Domain API](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#verify-domain-ownership) : [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#domain-verification-apis) Domain Verification APIs ----------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#generate-dns-txt-record) Generate DNS TXT Record Generate a unique DNS TXT record for domain verification. **Endpoint:** `GET /dedi/generate-dns-txt/{namespace_id}/{domain}` **Parameters:** * `namespace_id` (path, required): Target namespace identifier * `domain` (path, required): Domain to verify * `verification_method` (query or body, required): One of `self_dns`, `self_http`, or `request_other_namespace` * `target_namespace` (query or body, required for `request_other_namespace`): Namespace ID or verified domain of the attesting namespace **Validation Rules:** * Domain must contain a dot (valid format) * Namespace must exist * Domain cannot already be actively verified by another namespace * `self_dns` and `self_http` require the domain to be present in the DeDi.global global registry * `request_other_namespace` requires a self-verified target namespace **Example Request:** **Success Response (200):** **TXT Record Already Exists (200):** **Delegated Verification Request Created (200):** **Error Responses:** * `400` - Invalid domain format, invalid verification method, missing `target_namespace`, or domain/namespace state conflict * `404` - Namespace not found or target namespace not found * `500` - Failed to generate verification string ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#verify-domain-ownership) Verify Domain Ownership Verify domain ownership by checking the TXT record in DNS. **Endpoint:** `POST /dedi/verify-domain` **Request Body:** **Prerequisites:** * TXT record must be generated first using the Generate DNS TXT API * For `self_dns`, TXT record must be added to domain DNS * For `self_http`, the TXT value must be served from `/.well-known/dedi-verification.txt` * DNS propagation should be complete (allow 5-30 minutes) **Verification Process:** 1. Validates the namespace exists 2. Retrieves the generated self-verification record 3. Attempts DNS TXT verification first 4. Falls back to HTTP verification at `/.well-known/dedi-verification.txt` if DNS verification does not succeed 5. Updates namespace and domain verification status if a proof matches **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Namespace ID missing, verification file content mismatch, or domain is already in use * `404` - Namespace not found or no self-verification TXT has been generated * `500` - Internal verification errors **Important Notes:** * DNS changes may take time to propagate (typically 5-30 minutes, up to 48 hours in rare cases) * HTTP verification is attempted after DNS verification if DNS does not match * Only self-managed verification records are verified through this endpoint * Verified domains cannot be shared between multiple namespaces ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#check-verification-status) Check Verification Status Check the current verification status of a namespace's associated domain. **Endpoint:** `GET /dedi/check-verification/{namespace_id}` **Parameters:** * `namespace_id` (path, required): Target namespace ID to check **Example Request:** **Verified Namespace Response (200):** **Unverified Namespace Response (200):** **Error Responses:** * `400` - Namespace ID required * `404` - Namespace not found * `500` - Internal server error **Use Cases:** * Check if domain verification is complete before proceeding with operations * Retrieve the verified domain name for a namespace * Display verification status in user interfaces * Validate namespace credibility before trusting data ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#get-dns-txt-record) Get DNS TXT Record Retrieve the generated DNS TXT record and verification details for a namespace. **Endpoint:** `GET /dedi/get-dns-txt/{namespace_id}` **Parameters:** * `namespace_id` (path, required): Target namespace identifier **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Namespace ID required * `404` - Domain not found for namespace (TXT record not generated) * `500` - Internal server error **Use Cases:** * Retrieve TXT record after generation for DNS configuration * Check domain and current verification status * Audit domain verification setup * Get verification string for manual DNS configuration * Troubleshoot verification issues ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#remove-namespace-verification) Remove Namespace Verification Remove domain verification from a namespace, reverting it to unverified status. **Endpoint:** `POST /dedi/{namespace}/{domain}/remove-namespace-verification` **Parameters:** * `namespace` (path, required): Namespace ID to remove verification from * `domain` (path, required): Domain whose verification should be removed **Prerequisites:** * Namespace must exist * Domain must be associated with the namespace either through self-verification or an accepted delegated verification request **Process:** 1. Validates the namespace exists 2. Removes matching domain-verification entries and accepted/pending delegated requests for that domain 3. Recomputes namespace verification state 4. Clears the domain from the namespace only if no active verification source remains **Example Request:** **Success Response (200):** **Error Responses:** * `400` - Namespace ID or domain parameter missing * `404` - Namespace not found or no verification data exists for the provided namespace/domain pair * `500` - Internal server error while removing verification **Use Cases:** * Decommission domain verification when changing domain strategy * Reset namespace to unverified state for re-verification with different domain * Remove verification due to domain ownership changes * Clean up verification when domain is no longer controlled by namespace owner * Prepare namespace for transfer to different domain owner **Important Notes:** * Removing verification does not delete the namespace itself * If multiple verification sources still exist for the same domain, the namespace may remain verified * The namespace can be re-verified with the same or different domain later [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#verification-request-apis) Verification Request APIs ------------------------------------------------------------------------------------------------------------------------------------- Delegated domain verification uses verification requests and notification APIs. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#list-pending-verification-notifications) List Pending Verification Notifications **Endpoint:** `GET /dedi/notifications/pending` **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#list-notification-history) List Notification History **Endpoint:** `GET /dedi/notifications/history` **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#mark-a-notification-as-read) Mark a Notification as Read **Endpoint:** `POST /dedi/notifications/{notification_id}/read` **Request Body:** None **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#mark-all-notifications-as-read) Mark All Notifications as Read **Endpoint:** `POST /dedi/notifications/read-all` **Request Body:** None **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#accept-a-verification-request) Accept a Verification Request **Endpoint:** `POST /dedi/verification-requests/{request_id}/accept` **Request Body:** None **Success Response (200):** ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#reject-a-verification-request) Reject a Verification Request **Endpoint:** `POST /dedi/verification-requests/{request_id}/reject` **Request Body:** None **Success Response (200):** [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#domain-re-verification) Domain Re-verification ------------------------------------------------------------------------------------------------------------------------------- Verified domains are re-checked on a scheduled basis. * Self-managed verification sources (`self_dns`, `self_http`) and accepted delegated verification sources (`request_other_namespace`) participate in re-verification. * The current implementation re-verifies active sources after a configurable interval. The default interval is `1` year. * If a re-verification attempt fails, the source enters a configurable grace period. The default grace period is `7` days. * If the verification source is restored during the grace period, the source remains active. * If the source still fails after the grace period, that verification source is removed. * If no active verification source remains for the domain, the domain is removed from the namespace verification state. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#best-practices) Best Practices --------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#dns-configuration) DNS Configuration 1. **Use Minimal TTL**: Set TTL to 300 seconds (5 minutes) during verification for faster propagation 2. **Test Before Verification**: Use online DNS checker tools to confirm TXT record is visible 3. **Allow Propagation Time**: Wait 5-30 minutes after adding TXT record before attempting verification ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#security-considerations) Security Considerations 1. **Domain Control**: Only add TXT records if you have legitimate control of the domain 2. **Monitor Verification Status**: Regularly check verification status to ensure it remains valid ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#troubleshooting) Troubleshooting **Common Issues:** * **DNS Propagation Delay**: Wait longer and try verification again * **Incorrect TXT Record**: Ensure the entire and exact string is copied without modifications * **Domain Not Whitelisted**: Contact DeDi.global support to whitelist your domain * **Multiple TXT Records**: Some DNS providers require specific formatting for multiple TXT records **Verification Failed?** 1. Check TXT record is correctly added to DNS 2. Verify domain propagation using online DNS tools 3. Ensure namespace exists and hasn't been verified with another domain 4. Contact support if domain should be whitelisted but isn't recognized [PreviousAccess APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access) [NextDelegation Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/delegation) Last updated 1 month ago Was this helpful? * [Why Domain Verification Matters](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#why-domain-verification-matters) * [Trust Through Domain Ownership](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#trust-through-domain-ownership) * [The Verification Advantage](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#the-verification-advantage) * [Real-World Example](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#real-world-example) * [How Domain Verification Works](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#how-domain-verification-works) * [1\. Namespace Creation](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-1.-namespace-creation) * [2\. Choose a Verification Method](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-2.-choose-a-verification-method) * [3\. Domain Whitelisting / Global Registry Check](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-3.-domain-whitelisting-global-registry-check) * [4\. Verification Record Generation](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-4.-verification-record-generation) * [5\. Publish the Proof](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-5.-publish-the-proof) * [6\. Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#id-6.-verification) * [Domain Verification APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#domain-verification-apis) * [Generate DNS TXT Record](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#generate-dns-txt-record) * [Verify Domain Ownership](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#verify-domain-ownership) * [Check Verification Status](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#check-verification-status) * [Get DNS TXT Record](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#get-dns-txt-record) * [Remove Namespace Verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#remove-namespace-verification) * [Verification Request APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#verification-request-apis) * [List Pending Verification Notifications](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#list-pending-verification-notifications) * [List Notification History](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#list-notification-history) * [Mark a Notification as Read](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#mark-a-notification-as-read) * [Mark All Notifications as Read](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#mark-all-notifications-as-read) * [Accept a Verification Request](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#accept-a-verification-request) * [Reject a Verification Request](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#reject-a-verification-request) * [Domain Re-verification](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#domain-re-verification) * [Best Practices](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#best-practices) * [DNS Configuration](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#dns-configuration) * [Security Considerations](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#security-considerations) * [Troubleshooting](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/domain#troubleshooting) Was this helpful? GitBook AssistantAskCopy const namespaceResponse = await fetch('https://api.dedi.global/dedi/create-namespace', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'techcorp-data', description: 'TechCorp official data namespace', meta: { company: 'TechCorp Inc.', industry: 'Technology' } }) }); GitBook AssistantAskCopy const txtResponse = await fetch('https://api.dedi.global/dedi/generate-dns-txt/your-namespace-id/techcorp.com?verification_method=self_dns', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); GitBook AssistantAskCopy Record Type: TXT Host: @ (or your domain) Value: [generated verification string] <-- make sure you copy the entire DNS TXT(i.e. dedi-verification=abcdefg1234567) TTL: 300 (or minimum allowed) GitBook AssistantAskCopy https:///.well-known/dedi-verification.txt GitBook AssistantAskCopy const verifyResponse = await fetch('https://api.dedi.global/dedi/verify-domain', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ namespace_id: 'your-namespace-id' }) }); GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/generate-dns-txt/did:cord:3yVazTQMc.../techcorp.com?verification_method=self_dns', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Generated domain's DNS TXT record", "txt": "dedi-verification=abcdefg1234567" } GitBook AssistantAskCopy { "message": "TXT is already generated", "data": { "txt": "dedi-verification=abcdefg1234567" } } GitBook AssistantAskCopy { "message": "Verification request created", "data": { "request_id": "uuid", "txt": "dedi-verification=abcdefg1234567", "target_namespace": "did:cord:..." } } GitBook AssistantAskCopy { namespace_id: string; // Namespace ID to verify domain?: string; // Optional when multiple self-verification records exist } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/verify-domain', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ namespace_id: 'did:web:did.cord.network:76E...' }) }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Verification Successful" } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/check-verification/did:web:did.cord.network:76E...', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "verified": true, "domain": "techcorp.com" } GitBook AssistantAskCopy { "verified": false } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/get-dns-txt/did:web:did.cord.network:76E...', { method: 'GET', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "namespace_id": "did:web:did.cord.network:76E...", "domain": "techcorp.com", "txt": "dedi-verification=abcdefg1234567", "is_verified": true } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/did:web:did.cord.network:76E.../techcorp.com/remove-namespace-verification', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' } }); const data = await response.json(); GitBook AssistantAskCopy { "message": "Namespace verification removed successfully", "data": { "domain": "techcorp.com", "verification_methods": ["self_dns"], "removed_targets": [], "removed_entries": 1, "domain_removed_from_namespace": true, "domain_still_verified": false } } GitBook AssistantAskCopy { "message": "Unread verification notifications retrieved successfully", "unread_count": 2, "data": [\ {\ "id": "vrn_...",\ "request_id": "vr_...",\ "namespace_id": "did:cord:...",\ "target_namespace_id": "did:cord:...",\ "recipient_email": "[emailΒ protected]",\ "actor_email": null,\ "domain": "example.com",\ "event_type": "pending",\ "title": "Verification request pending",\ "message": "A namespace has requested domain attestation.",\ "metadata": {},\ "is_read": false,\ "read_at": null,\ "created_at": "2026-05-04T08:30:00.000Z",\ "updated_at": "2026-05-04T08:30:00.000Z"\ }\ ] } GitBook AssistantAskCopy { "message": "Verification notification history retrieved successfully", "data": [\ {\ "id": "vrn_...",\ "request_id": "vr_...",\ "recipient_email": "[emailΒ protected]",\ "domain": "example.com",\ "event_type": "accepted",\ "is_read": true,\ "read_at": "2026-05-04T08:45:00.000Z"\ }\ ] } GitBook AssistantAskCopy { "message": "Notification marked as read", "data": { "id": "vrn_...", "is_read": true, "read_at": "2026-05-04T08:45:00.000Z" } } GitBook AssistantAskCopy { "message": "All notifications marked as read", "data": { "affected": 2 } } GitBook AssistantAskCopy { "message": "Verification request accepted", "data": { "request_id": "vr_...", "registry_id": "did:cord:registry:...", "record_id": "did:cord:record:..." } } GitBook AssistantAskCopy { "message": "Verification request rejected" } --- # Publish APIs | DeDi | NFH Fabric The Publish APIs enable you to create and manage the core components of your data infrastructure on DeDi.global. These APIs allow you to organize data hierarchically through namespaces, define structured schemas via registries, and store individual records with full lifecycle management. **Authentication**: πŸ”’ All Publish APIs require authentication via API key. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#core-concepts) Core Concepts -------------------------------------------------------------------------------------------------------------- Before diving into the APIs, it's essential to understand DeDi.global's hierarchical structure: * **Namespace**: A top-level container that organizes related registries * **Registry**: Defines the structure and schema for a specific type of data * **Record**: Individual data entries conforming to a registry's schema [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#namespace-management) Namespace Management ---------------------------------------------------------------------------------------------------------------------------- Namespaces provide isolation and organization for your data. They act as containers for related registries and can be associated with verified domains for enhanced trust. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#create-namespace) Create Namespace Create a new namespace to organize your registries and establish data boundaries. **Endpoint**: `POST /dedi/create-namespace` **Request Body**: GitBook AssistantAskCopy { name: string; // Unique namespace name description: string; // Purpose and description of the namespace meta?: object; // Optional metadata for additional context version_count?: number; // Optional version number for tracking } **Example Request**: **Response**: **Error Scenarios**: * `400` - Invalid request body * `401` - Missing or invalid API key * `409` - Namespace name already exists * `429` - Rate limit exceeded **Use Cases**: * Organizing data by department, project, or domain * Creating isolated environments for different applications * Setting up customer-specific data spaces [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#registry-management) Registry Management -------------------------------------------------------------------------------------------------------------------------- Registries define the structure and validation rules for the data you want to store. They act as templates that ensure data consistency and enable powerful querying capabilities. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#create-registry) Create Registry Define a new registry within a namespace to store structured records. **Endpoint**: `POST /dedi/{namespace}/create-registry` **Path Parameters**: * `namespace` - Namespace ID or verified domain name **Request Body**: Provide either `schema` or `tag`. Do not send both in the same request. **Example Request**: **Response**: **Schema Tags**: DeDi.global currently provides 5 pre-built schemas out of the box: * `membership` - Identity and membership data schemas * `public_key` - Cryptographic public key schemas * `revoke` - Revocation and status tracking schemas * `beckn_subscriber` - Beckn protocol subscriber information * `beckn_subscriber_reference` - Beckn protocol subscriber reference data **Note**: When using any of the pre-built schema tags (`membership`, `public_key`, `revoke`, `beckn_subscriber`, `beckn_subscriber_reference`), provide `tag` and omit `schema`. For custom registries, provide `schema` and omit `tag`. _For detailed information about these pre-built schemas, please reach out to our support team._ **Error Scenarios**: * `400` - Invalid schema format or invalid `schema`/`tag` combination * `404` - Namespace not found * `403` - Insufficient permissions for the namespace * `409` - Registry name already exists in the namespace [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#time-to-live-ttl-management) Time to Live (TTL) Management -------------------------------------------------------------------------------------------------------------------------------------------- DeDi.global supports automatic expiration of data through Time to Live (TTL) values, which can be set at both the registry and record levels. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#ttl-behavior) TTL Behavior * **Registry TTL**: Sets the default TTL(i.e. 600) for the registry. This can be updated as per use. * **Record TTL**: Sets the default TTL(i.e. 600) for the records. This can be updated as per use. * **Expiration**: Once TTL expires, the cache is cleared. * **TTL Units**: Specified in seconds (e.g., 86400 for 24 hours, 604800 for 7 days) ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#setting-ttl-values) Setting TTL Values TTL can be overwritten during updates: ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#ttl-best-practices) TTL Best Practices * **Session Data**: Use short TTL (minutes to hours) for temporary session information * **User Profiles**: Use longer TTL (weeks to months) for stable user data * **Audit Logs**: Consider no TTL or very long TTL for compliance requirements * **Cache Data**: Use short TTL for frequently updated cache entries [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#record-management) Record Management ---------------------------------------------------------------------------------------------------------------------- Records are individual data entries that conform to a registry's schema. DeDi.global supports a draft-and-publish workflow for better data quality control. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#save-record-as-draft) Save Record as Draft Create a record in draft state for review before publishing. **Endpoint**: `POST /dedi/{namespace}/{registry_name}/save-record-as-draft` **Path Parameters**: * `namespace` - Namespace ID or verified domain * `registry_name` - Target registry name **Query Parameters**: * `publish` - Set to `true` to save and publish immediately (optional) **Request Body**: **Example Request**: **Response**: When `publish=true`, the response is: ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#publish-records) Publish Records Queue one or more draft records for publishing so they transition to live state and become queryable. **Endpoint**: `POST /dedi/{namespace}/{registry_name}/publish-records` **Path Parameters**: * `namespace` - Namespace ID or verified domain * `registry_name` - Registry containing the draft records **Request Body**: **Example Request**: **Response**: **Important Notes**: * Every listed record must already exist in `draft` state. * The target registry must be in `live` state. * Publishing is queued and returns the generated record IDs for the submitted draft records. * Published records are then available through lookup and query APIs. [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#data-export) Data Export ---------------------------------------------------------------------------------------------------------- Export registry data for analysis, backup, or migration purposes. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#export-records-as-csv) Export Records as CSV Download all records from a registry in CSV format. **Endpoint**: `GET /dedi/{namespace}/{registry_name}/export-as-csv` **Path Parameters**: * `namespace` - Namespace ID or verified domain * `registry_name` - Registry to export **Example Request**: **Response**: * Content-Type: `text/csv` * CSV file with all registry records **CSV Format**: * Headers match registry schema fields * Nested objects flattened with dot notation * Includes record metadata (ID, timestamps, state) * One row per record [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#bulk-operations) Bulk Operations ------------------------------------------------------------------------------------------------------------------ Handle large-scale data operations efficiently through asynchronous job processing. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#bulk-upload-records) Bulk Upload Records Upload multiple records via CSV files with asynchronous processing. **Endpoint**: `POST /dedi/bulk-upload` **Request Format**: `multipart/form-data` **Form Fields**: * `namespace` - Target namespace ID or verified domain (required) * `registry_name` - Target registry name (required) * `record_name_field` - CSV column to use as `record_name` (optional) * `file` - Single CSV file upload (required, max 100MB) **Example Request**: **Response**: ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#check-job-status) Check Job Status Monitor the progress of bulk upload operations. **Endpoint**: `GET /dedi/bulk-upload/status/{jobId}` **Path Parameters**: * `jobId` - Job ID returned from bulk upload **Example Request**: **Response**: **Job States**: * `pending` - Job queued, waiting to start * `processing` - Currently processing rows * `completed` - Processing finished * `failed` - Job failed with errors **Polling Recommendation**: Check status every 5-10 seconds during processing. ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#get-user-jobs) Get User Jobs Retrieve a list of all bulk upload jobs for the authenticated user. **Endpoint**: `GET /dedi/bulk-upload/jobs` **Query Parameters**: * `page` - Page number (default: 1) * `limit` - Jobs per page (default: 10, max: 100) **Example Request**: **Response**: ### [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#download-registry-csv-template) Download Registry CSV Template Download a schema-derived CSV template for a registry. **Endpoint**: `GET /dedi/{namespace}/{registry_name}/download-sample-csv` **Path Parameters**: * `namespace` - Namespace ID or verified domain * `registry_name` - Registry name **Example Request**: **Success Response (200):** * Content type: `text/csv` * Content disposition: `attachment; filename={registry_name}_template.csv` **Error Scenarios**: * `400` - Registry schema not found or schema has no exportable fields * `404` - Namespace not found or registry not found * `500` - Failed to export CSV template [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#csv-format-requirements) CSV Format Requirements ---------------------------------------------------------------------------------------------------------------------------------- When using bulk upload, ensure your CSV files follow these guidelines: **File Format**: * Valid UTF-8 encoding * First row must contain field names matching registry schema * Maximum file size: 100MB * Supported extensions: `.csv` * Upload exactly one CSV file per request **Data Format**: * Nested objects: Use dot notation (e.g., `address.street`, `address.city`) * Arrays: Use comma-separated values within quotes * Dates: ISO 8601 format recommended * Boolean: `true`/`false` or `1`/`0` **Example JSON Schema**: **Example CSV**: [](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#error-handling) Error Handling ---------------------------------------------------------------------------------------------------------------- Common error scenarios and their resolutions: **Schema Validation Errors**: * Ensure record data matches registry schema exactly * Check required fields are present * Validate data types and formats **Permission Errors**: * Verify you have write access to the namespace/registry * Check if you're a delegate with appropriate permissions **Rate Limiting**: * Bulk operations have special rate limits * Monitor rate limit headers in responses * Implement exponential backoff for retries **Troubleshooting Tips**: * Use draft mode to test record formats before publishing * Start with small CSV files for bulk uploads * Monitor job status regularly for long-running operations * Keep API keys secure and rotate them periodically [PreviousAPI Reference](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis) [NextAccess APIs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/access) Last updated 1 month ago Was this helpful? * [Core Concepts](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#core-concepts) * [Namespace Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#namespace-management) * [Create Namespace](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#create-namespace) * [Registry Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#registry-management) * [Create Registry](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#create-registry) * [Time to Live (TTL) Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#time-to-live-ttl-management) * [TTL Behavior](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#ttl-behavior) * [Setting TTL Values](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#setting-ttl-values) * [TTL Best Practices](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#ttl-best-practices) * [Record Management](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#record-management) * [Save Record as Draft](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#save-record-as-draft) * [Publish Records](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#publish-records) * [Data Export](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#data-export) * [Export Records as CSV](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#export-records-as-csv) * [Bulk Operations](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#bulk-operations) * [Bulk Upload Records](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#bulk-upload-records) * [Check Job Status](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#check-job-status) * [Get User Jobs](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#get-user-jobs) * [Download Registry CSV Template](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#download-registry-csv-template) * [CSV Format Requirements](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#csv-format-requirements) * [Error Handling](https://docs.nfh.global/dedi/dedi.global-developers/standard-apis/publish#error-handling) Was this helpful? GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/create-namespace', { method: 'POST', headers: { 'Authorization': `Bearer ${your_api_key}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: 'employee-directory', description: 'Corporate employee information and credentials', meta: { department: 'Human Resources', company: 'Acme Corporation' } }) }); const namespace = await response.json(); GitBook AssistantAskCopy { message: string; // Success confirmation message data: { namespace_id: string; // Unique identifier for the created namespace } } GitBook AssistantAskCopy { registry_name: string; // Unique registry name within the namespace description: string; // Description of what this registry stores schema?: object; // Custom JSON Schema defining record structure tag?: 'membership' | 'public_key' | 'revoke' | 'beckn_subscriber' | 'beckn_subscriber_reference'; // Pre-built schema tag meta?: object; // Optional metadata } GitBook AssistantAskCopy const registryData = { registry_name: 'employee-profiles', description: 'Employee profile information including roles and contact details', schema: { type: 'object', properties: { employee_id: { type: 'string', pattern: '^EMP[0-9]{6}$' }, full_name: { type: 'string', minLength: 1 }, email: { type: 'string', format: 'email' }, department: { type: 'string', enum: ['Engineering', 'HR', 'Sales'] }, hire_date: { type: 'string', format: 'date' }, active: { type: 'boolean', default: true } }, required: ['employee_id', 'full_name', 'email', 'department'] }, meta: { version: '1.0', data_classification: 'internal' } }; const response = await fetch(`https://api.dedi.global/dedi/employee-directory/create-registry`, { method: 'POST', headers: { 'Authorization': `Bearer ${your_api_key}`, 'Content-Type': 'application/json' }, body: JSON.stringify(registryData) }); GitBook AssistantAskCopy { message: string; // Success confirmation message data: { registry_id: string; // Unique registry identifier } } GitBook AssistantAskCopy // Registry update to 24 hour TTL { "description": "User session data", "tag": "custom", "ttl": 86400, // default is 600 "meta": {} } // Record update to 7-day TTL { "description": "User session for mobile app", "details": { /* session data */ }, "valid_till": , // Expiration date in ISO format "ttl": 604800, "meta": {} } GitBook AssistantAskCopy { record_name: string; // Unique record name within the registry description: string; // Record description details: object; // Record data matching registry schema meta?: object; // Application-specific metadata valid_till?: string; // Expiration date in ISO format } GitBook AssistantAskCopy const recordData = { record_name: 'john-doe-profile', description: 'Employee profile for John Doe in Engineering', details: { employee_id: 'EMP123456', full_name: 'John Doe', email: '[emailΒ protected]', department: 'Engineering', hire_date: '2024-01-15', active: true }, meta: { created_by: 'hr-system', data_source: 'employee_onboarding_form' }, valid_till: '2025-12-31T23:59:59Z' }; const response = await fetch( `https://api.dedi.global/dedi/employee-directory/employee-profiles/save-record-as-draft`, { method: 'POST', headers: { 'Authorization': `Bearer ${your_api_key}`, 'Content-Type': 'application/json' }, body: JSON.stringify(recordData) } ); GitBook AssistantAskCopy { message: "record saved as draft"; data: { record_name: string; } } GitBook AssistantAskCopy { message: "record created"; data: { record_id: string; } } GitBook AssistantAskCopy { records: string[]; // One or more draft record names } GitBook AssistantAskCopy const response = await fetch( `https://api.dedi.global/dedi/employee-directory/employee-profiles/publish-records`, { method: 'POST', headers: { 'Authorization': `Bearer ${your_api_key}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ records: ['john-doe-profile', 'jane-doe-profile'] }) } ); GitBook AssistantAskCopy { message: string; // "Records are in publish queue" data: { count: number; record_ids: string[]; } } GitBook AssistantAskCopy const response = await fetch( `https://api.dedi.global/dedi/employee-directory/employee-profiles/export-as-csv`, { headers: { 'Authorization': `Bearer ${your_api_key}` } } ); // Handle CSV download const csvData = await response.text(); const blob = new Blob([csvData], { type: 'text/csv' }); GitBook AssistantAskCopy const formData = new FormData(); formData.append('namespace', 'employee-directory'); formData.append('registry_name', 'employee-profiles'); formData.append('file', csvFile); const response = await fetch('https://api.dedi.global/dedi/bulk-upload', { method: 'POST', headers: { 'Authorization': `Bearer ${your_api_key}` }, body: formData }); const job = await response.json(); GitBook AssistantAskCopy { status: string; // "success" total_rows: number; // Parsed CSV row count reported in the response message: string; // Success confirmation message data: { jobId: string; // Unique job identifier for status tracking statusCheckUrl: string; // Relative URL to check job progress } } GitBook AssistantAskCopy const response = await fetch(`https://api.dedi.global/dedi/bulk-upload/status/${job_id}`, { headers: { 'Authorization': `Bearer ${your_api_key}` } }); const status = await response.json(); GitBook AssistantAskCopy { status: string; // "success" message: string; // Success confirmation message data: { jobId: string; // Job identifier createdAt: string; // Job creation timestamp updatedAt: string; // Last update timestamp status: 'pending' | 'processing' | 'completed' | 'failed'; namespace: string; // Target namespace registryName: string; // Target registry totalEntries: number; // Rows discovered in the CSV validEntries: number; // Successfully processed rows failedEntries: number; // Failed rows error?: string; // Error message if job failed result?: object; // Final processing summary if available failedEntriesUrl?: string | null; downloadFailedEntriesCsvUrl?: string | null; } } GitBook AssistantAskCopy const response = await fetch('https://api.dedi.global/dedi/bulk-upload/jobs?page=1&limit=20', { headers: { 'Authorization': `Bearer ${your_api_key}` } }); const jobsList = await response.json(); GitBook AssistantAskCopy { status: string; // "success" message: string; // Success confirmation message data: { jobs: Array<{ jobId: string; // Job identifier status: string; // Job status createdAt: string; // Job creation timestamp updatedAt: string; // Last update timestamp namespace: string; // Target namespace error?: string; // Error message if failed }>; pagination: { page: number; // Current page number limit: number; // Items per page total: number; // Total number of jobs pages: number; // Total number of pages }; } } GitBook AssistantAskCopy curl -L \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://api.dedi.global/dedi/employee-directory/employee-profiles/download-sample-csv" \ -o employee-profiles_template.csv GitBook AssistantAskCopy { "type": "object", "properties": { "employee_id": { "type": "string" }, "personal_info": { "type": "object", "properties": { "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } } }, "employment": { "type": "object", "properties": { "department": { "type": "string" }, "position": { "type": "string" }, "hire_date": { "type": "string", "format": "date" } } }, "active": { "type": "boolean" }, "skills": { "type": "array", "items": { "type": "string" } } } } GitBook AssistantAskCopy employee_id,personal_info.full_name,personal_info.email,personal_info.phone,employment.department,employment.position,employment.hire_date,active,skills EMP123456,John Doe,[emailΒ protected],+1-555-0123,Engineering,Senior Developer,2024-01-15,true,"JavaScript,TypeScript,Node.js" EMP123457,Jane Smith,[emailΒ protected],+1-555-0124,Sales,Sales Manager,2024-02-01,true,"CRM,Negotiation,Analytics" --- # Welcome | Finternet | NFH Fabric This is the open documentation for building on the Finternet platform. Whether you are an issuer tokenising assets, a developer building applications, a token manager operating pools, or a trust provider issuing credentials β€” this is your starting point. ### [](https://docs.nfh.global/finternet#what-is-finternet) What is Finternet? Finternet is an open financial infrastructure protocol that enables tokenised digital assets to be transferred and programmably enforced across ledgers, jurisdictions, and institutions β€” without requiring global consensus. It is built around three core principles: * **User Centric** β€” Users control their own identity, keys, and assets. No intermediary holds custody by default. * **Unified** β€” A single account gives visibility across all token pools and external ledgers. No more siloed views. * **Universal** β€” Open to any participant, any asset type, any jurisdiction. Standards-based and extensible. ### [](https://docs.nfh.global/finternet#what-is-units) What is UNITS? **UNITS** (Unified Information Tokenisation System) is the core implementation of the Finternet protocol. It provides: * A **Token State Plane** β€” maintains authoritative (native) or replicated (proxy) records of who holds what, under what conditions. * A **Policy Enforcement Plane** β€” programmable rules (token programs, pre/post hooks) governing how tokens may be transferred, encumbered, or modified. * An **Identity and Credential Plane** β€” verifiable identifiers (DIDs), accounts, and a registry that anchors policy enforcement to real-world entities. ### [](https://docs.nfh.global/finternet#how-this-documentation-is-organised) How this documentation is organised Section What you will find [**Overview**](https://docs.nfh.global/finternet/overview/what-is-finternet) The vision, architecture, actor model, and glossary [**Concepts**](https://docs.nfh.global/finternet/concepts/accounts-and-identity) Deep dives into accounts, tokens, programs, state modes, commitments, delegation, and policy [**Building**](https://docs.nfh.global/finternet/building/building) Role-based guides: quickstart, token manager guide, app developer guide, trust provider guide [**Use Cases**](https://docs.nfh.global/finternet/use-cases/use-cases) Concrete examples: corporate vouchers, tokenised deposits, programmable payments [**Architecture**](https://docs.nfh.global/finternet/architecture/architecture) System components, data model, event processing, security, deployment [**Roadmap**](https://github.com/finternet-io/docs.finternetlab.io/blob/main/documentation/roadmap/README.md) Big-ticket items planned for the next two release cycles [**API Reference**](https://docs.finternetlab.io/api-reference/) Interactive OpenAPI documentation for all endpoints [NextWhat is Finternet?](https://docs.nfh.global/finternet/overview/what-is-finternet) Last updated 1 month ago Was this helpful? * [What is Finternet?](https://docs.nfh.global/finternet#what-is-finternet) * [What is UNITS?](https://docs.nfh.global/finternet#what-is-units) * [How this documentation is organised](https://docs.nfh.global/finternet#how-this-documentation-is-organised) Was this helpful? --- # Find catalogs using DISCOVR | Beckn Networks | NFH Fabric Welcome to the documentation for Beckn DISCOVR β€” the Discovery Service (DS) of the Beckn ecosystem. It is a high-performance, real-time discovery engine that enables consumers to find resources across all published catalogues in Beckn-enabled networks. This guide is intended for Consumer Node (CN) developers, consumer application builders, network facilitators, and anyone building search experiences on top of Beckn catalogues. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#what-is-beckn-discovr) What is Beckn DISCOVR? Beckn DISCOVR is the query-time search and discovery layer for Beckn ecosystems. While Beckn CATALG (CS) acts as the source of truth for catalogue publishing and validation, DISCOVR (DS) is purpose-built for **real-time search** β€” it indexes catalogue data from CATALG and exposes it through fast, flexible query APIs that power consumer-facing search experiences. DISCOVR receives catalogue updates from CATALG (via subscription-based delivery), indexes them for search, and serves discovery requests from Consumer Nodes (CNs) and consumer applications with sub-second response times. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#why-do-you-need-beckn-discovr) Why Do You Need Beckn DISCOVR? Without a dedicated discovery layer, consumer applications face: * Querying raw catalogue data directly β€” slow, unstructured, and unscalable * Building custom search indexes per application β€” duplicated effort, inconsistent results * No support for natural language, spatial, or attribute-based search across providers * No unified view of resources across multiple catalogues and networks Beckn DISCOVR solves this by offering: * **One search endpoint** across all catalogues published to the network * **Multiple search modes** β€” natural language, keyword, spatial (location-based), and JSONPath attribute filtering * **Real-time indexing** β€” catalogue changes from CATALG are indexed and searchable within seconds * **Provider-agnostic results** β€” consumers see resources from all providers, with offers from multiple retailers in one response ### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#key-capabilities) Key Capabilities #### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#for-consumer-nodes-cns) For Consumer Nodes (CNs) * **Natural language search** β€” ask questions like "strong Assam tea for morning chai" or "premium coffee under 500 rupees" * **Keyword search** β€” find resources by name, description, brand, or any indexed attribute * **Spatial search** β€” find resources available near a location using GeoJSON coordinates and distance radius * **Attribute filtering** β€” query resources and offers using JSONPath expressions for fine-grained filtering (e.g., "flat discount offers under β‚Ή100") * **Combined queries** β€” mix text search with spatial constraints in a single request * **Schema-aware results** β€” responses include full resource attributes, ratings, offers, and provider details #### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#for-discovery-service-ds-builders) For Discovery Service (DS) Builders * **Subscription-driven indexing** β€” DISCOVR subscribes to CATALG and receives catalogue updates automatically via `POST /catalog/push` * **Full-text and spatial search** β€” supports keyword matching, natural language understanding, and geospatial proximity queries * **Quality-assured results** β€” incoming catalogues are validated, deduplicated, and pruned before being served to consumers #### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#for-network-facilitators) For Network Facilitators * **Network-wide search** β€” query across all providers and catalogues in a network * **Schema type filtering** β€” discover resources by domain type (e.g., GroceryItem, ChargingService, HealthcareProvider) * **Offer comparison** β€” see multiple retailer offers for the same resource in one response * **Real-time availability** β€” search results reflect the latest published catalogue state ### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#high-level-architecture) High-Level Architecture ### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#example-use-case) Example Use Case A consumer opens a grocery shopping app and searches for "instant coffee near me". The Consumer Node (CN) sends a discover request to Beckn DISCOVR combining natural language text search with a spatial constraint (5 km radius around the consumer's location). DISCOVR queries its search index for resources matching "instant coffee" and its spatial index for resources with availability locations within 5 km. The response includes multiple matching products from different providers β€” each with competing offers showing different prices, discounts, and delivery estimates. The consumer compares offers and proceeds to order from the provider with the best price and fastest delivery. ### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#design-principles) Design Principles * **Real-time query engine**: Optimized for sub-second search β€” not for catalogue storage or validation (that's CATALG's role) * **Subscription-driven**: Receives catalogue updates from CATALG automatically β€” no polling or manual sync * **Multi-modal search**: Supports text, natural language, spatial, and structured attribute queries β€” individually or combined * **Provider-agnostic**: Returns resources from all providers in a network, with competing offers side by side * **Schema-aware**: Understands Beckn resource and offer schemas β€” filters, groups, and prunes results based on schema context ### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#api-reference) API Reference DISCOVR exposes a single, powerful discovery endpoint that supports multiple search modes through the standard Beckn `discover` / `on_discover` flow. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#discovery-apis-consumer-node-facing) Discovery APIs (Consumer Node-facing) API Method Description `/discover` POST Asynchronous β€” acknowledges with `ACK`, delivers results via `POST /on_discover` callback to `bapUri` #### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#search-modes) Search Modes Mode Description Example **Text / Natural Language** Keyword or conversational query "strong Assam tea for morning chai" **Spatial** Find resources near a location Within 5 km of a GPS coordinate **Attribute Filter** Fine-grained filtering on resource or offer attributes Flat discount offers under β‚Ή100 **Combined** Mix any of the above in a single request Coffee search within 5 km radius For detailed request/response formats and examples, see the Catalog & Discovery APIs β€” Quick Reference. #### [](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#how-discovr-stays-updated) How DISCOVR Stays Updated DISCOVR does not poll CATALG for changes. Instead, it uses Beckn's subscription mechanism: 1. DISCOVR subscribes to CATALG using `POST /catalog/subscription` with `networkIds` and/or `schemaTypes` filters 2. When a provider publishes or updates a catalogue in CATALG, CATALG matches against active subscriptions 3. Matching catalogue data is delivered to DISCOVR via `POST /catalog/push` 4. DISCOVR indexes the received catalogue for search and spatial queries 5. The updated data is immediately searchable via `POST /discover` For historical data or initial sync, DISCOVR uses the CATALG Pull API (`POST /catalog/pull`) to fetch all existing catalogues. Last updated 10 days ago Was this helpful? * [What is Beckn DISCOVR?](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#what-is-beckn-discovr) * [Why Do You Need Beckn DISCOVR?](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#why-do-you-need-beckn-discovr) * [Key Capabilities](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#key-capabilities) * [High-Level Architecture](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#high-level-architecture) * [Example Use Case](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#example-use-case) * [Design Principles](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#design-principles) * [API Reference](https://docs.nfh.global/beckn/introduction-to-beckn/value-added-services/find-catalogs-using-discovr#api-reference) Was this helpful? GitBook AssistantAskCopy Beckn CATALG Beckn DISCOVR (source of truth) (search engine) | | | POST /catalog/push | | (catalogue updates delivered | | to subscribed DISCOVR instances) | |------------------------------------->| | | Index for search | | Store for spatial queries | | | | Consumer Node (CN) | | | | POST /discover | | (text / spatial / JSONPath) | |------------------------------------->| | | Query search + spatial indexes | POST /on_discover (callback) | | (matching resources + offers) | |<-------------------------------------| --- # How Finternet Compares | Finternet | NFH Fabric Finternet occupies a distinct design space β€” it is neither a traditional banking platform nor a public blockchain. This page clarifies the trade-offs and where Finternet fits. ### [](https://docs.nfh.global/finternet/overview/comparison#comparison-matrix) Comparison Matrix Dimension Traditional Banking Public Blockchain Finternet **Asset visibility** Siloed per institution. Each bank, broker, or insurer has its own portal. Visible on one chain. Cross-chain requires bridges. Unified across all conformant ledgers and institutions via a single account. **Programmability** None at the asset layer. Business rules live in middleware. Native via smart contracts, but scoped to one chain's VM. Native at the token layer (Rust programs + hooks) AND at the workflow layer (Restate orchestration). **Compliance** Each institution implements its own compliance. No portability. Largely absent. Bolted on via off-chain oracles or permissioned wrappers. Embedded in token policy. Per-jurisdiction trust domains. Credentials verified at transfer time. **Consensus** Centralised per institution. Trust the bank. Global consensus required (PoW, PoS). Expensive and slow. Per-pool trust. Each token manager operates independently. No global consensus needed. **Identity** Account number + institution ID. Not portable. Public key / address. Pseudonymous. No real-world binding. Finternet account + DID + Verifiable Credentials. Portable and real-world bound. **Settlement** T+1 to T+3 for most instruments. Near-instant on-chain, but finality varies. Near-instant for native. Adapter-dependent for proxy. **Custody** Institution holds custody. User has limited control. Self-custody via private keys. No recovery. MPC-based key generation. User controls keys. Recovery via passkeys and multi-device setup. **Interoperability** SWIFT, ACH β€” slow, expensive, limited to banks. Bridges β€” risky, fragmented, chain-specific. Adapters β€” standardised interface for any ledger or database. ### [](https://docs.nfh.global/finternet/overview/comparison#when-to-use-finternet) When to Use Finternet **Use Finternet when you need:** * A unified view of assets across multiple systems (banks, blockchains, internal databases) * Programmable business rules enforced at the asset layer, not in your application code * Compliance logic that travels with the token, not locked in one institution * Delegation and agentic workflows β€” software acting on behalf of users within scoped permissions * An open platform where multiple issuers, apps, and trust providers can participate **Finternet is not the right fit when you need:** * Censorship resistance (Finternet's trust model is institutional, not trustless) * Global consensus on a single shared state (Finternet uses per-pool trust) * Anonymous transactions (Finternet is identity-aware by design) ### [](https://docs.nfh.global/finternet/overview/comparison#the-trust-trade-off) The Trust Trade-off Finternet makes a deliberate trade-off: it gives up the censorship resistance and trustlessness of public blockchains in exchange for **institutional trust backed by cryptographic verifiability**. Users can independently verify their token state via commitment proofs β€” they do not need to trust UNITS blindly β€” but the system does not provide the same guarantees as a decentralised consensus network. This trade-off makes Finternet suitable for regulated financial use cases where institutions are already trusted actors, but where programmability, interoperability, and user control are currently missing. [PreviousThe Actor Model](https://docs.nfh.global/finternet/overview/actors) [NextGlossary](https://docs.nfh.global/finternet/overview/glossary) Last updated 2 months ago Was this helpful? * [Comparison Matrix](https://docs.nfh.global/finternet/overview/comparison#comparison-matrix) * [When to Use Finternet](https://docs.nfh.global/finternet/overview/comparison#when-to-use-finternet) * [The Trust Trade-off](https://docs.nfh.global/finternet/overview/comparison#the-trust-trade-off) Was this helpful? --- # How It Works: The Three Planes | Finternet | NFH Fabric Finternet's architecture is organised into three interacting planes. Each plane handles a distinct concern, and together they provide the full stack for tokenised asset management. spinner [](https://docs.nfh.global/finternet/overview/how-it-works#id-1.-token-state-plane) 1\. Token State Plane -------------------------------------------------------------------------------------------------------------- The Token State Plane is the authoritative (or replicated) record of **who holds what, under what conditions**. ### [](https://docs.nfh.global/finternet/overview/how-it-works#native-mode) Native Mode When UNITS is the source of truth, tokens live in **native token pools**. UNITS maintains the complete allocation history, enforces all operations through token programs, and generates cryptographic commitments (SHA-256 chained hashes) for every state change. This is the mode for newly issued digital assets β€” tokenised deposits, vouchers, credentials β€” where no external ledger is involved. ### [](https://docs.nfh.global/finternet/overview/how-it-works#proxy-mode) Proxy Mode When an external ledger (Ethereum, Solana, a private database) is the source of truth, UNITS maintains a **read-shadow** via adapters. The external ledger remains authoritative; UNITS provides a unified view and policy layer on top. This is the mode for existing on-chain assets or legacy systems where you want to bring them into the Finternet unified view without migrating them. ### [](https://docs.nfh.global/finternet/overview/how-it-works#commitments) Commitments Every token state change produces a **per-token commitment** β€” a SHA-256 hash chaining the previous commitment, transaction ID, timestamp, and full state. This gives users an independently verifiable proof that their token state has not been tampered with. At the block level, **Merkle commitments** (BLAKE3-based Merkle trees) aggregate batched transactions into a signed root, providing block-level auditability and finality. [](https://docs.nfh.global/finternet/overview/how-it-works#id-2.-policy-enforcement-plane) 2\. Policy Enforcement Plane ---------------------------------------------------------------------------------------------------------------------------- The Policy Enforcement Plane defines **how tokens may be transferred, encumbered, or modified**. This is where programmability lives. ### [](https://docs.nfh.global/finternet/overview/how-it-works#token-programs) Token Programs Token programs are pluggable Rust implementations that define the behaviour of each operation: mint, burn, transfer, freeze, lock, update, add claim, revoke claim. Each program includes validators that run before state changes are persisted. ### [](https://docs.nfh.global/finternet/overview/how-it-works#pre-post-hooks) Pre/Post Hooks Hooks are lifecycle callbacks attached to token classes: * **Pre-hooks** run before an operation and can reject it (e.g., max supply check, minimum balance requirement, credential verification). * **Post-hooks** run after an operation succeeds (e.g., emit an event, update an external system, notify a webhook). Token managers configure hooks when registering a token class, allowing business rules to be enforced without modifying the core programs. ### [](https://docs.nfh.global/finternet/overview/how-it-works#compliance-rules) Compliance Rules Policy enforcement is designed to be jurisdictional. Token classes can carry compliance rules that vary by jurisdiction β€” KYC requirements, transfer restrictions, reporting obligations. These rules are evaluated at transfer time through the hook system. [](https://docs.nfh.global/finternet/overview/how-it-works#id-3.-identity-and-credential-plane) 3\. Identity and Credential Plane -------------------------------------------------------------------------------------------------------------------------------------- The Identity and Credential Plane anchors policy enforcement to **real-world entities and jurisdictions**. ### [](https://docs.nfh.global/finternet/overview/how-it-works#finternet-accounts) Finternet Accounts Every participant has a Finternet account identified by: * A **UUIDv7 address** (time-sortable, database-optimised internal identifier) * A **DID** (Decentralized Identifier, `did:web` standard, publicly verifiable) * Contact methods (email, phone β€” hashed and encrypted) Accounts are controlled by cryptographic key pairs generated on the user's device using MPC (Multi-Party Computation) key generation. Private keys never leave the device. ### [](https://docs.nfh.global/finternet/overview/how-it-works#registry) Registry The registry maps identifiers to accounts. Given an email, phone number, or DID, the registry resolves to the corresponding Finternet account address. This enables human-friendly addressing while maintaining cryptographic security. ### [](https://docs.nfh.global/finternet/overview/how-it-works#verifiable-credentials) Verifiable Credentials Credentials (KYC attestations, accreditation certificates, compliance proofs) are issued by Trust Providers and bound to Finternet accounts. Token programs can require specific credentials as a precondition for transfer β€” e.g., "only transfer this security token to a holder with an accredited investor credential." [](https://docs.nfh.global/finternet/overview/how-it-works#how-the-planes-interact) How the Planes Interact ---------------------------------------------------------------------------------------------------------------- A concrete example β€” transferring a tokenised security: 1. **Identity Plane** β€” The sender and recipient are identified by their Finternet accounts. The system verifies both have valid KYC credentials from a recognised Trust Provider. 2. **Policy Plane** β€” The token program's pre-hook checks that the recipient holds an "accredited investor" credential and that the transfer does not violate the token class's jurisdictional rules. 3. **State Plane** β€” The transfer is executed: the sender's allocation is decremented, the recipient's is incremented, and a new commitment hash is generated for both tokens. The result: a compliant, auditable, programmable transfer β€” with the compliance logic embedded in the infrastructure, not in the application. [PreviousWhat is Finternet?](https://docs.nfh.global/finternet/overview/what-is-finternet) [NextThe Actor Model](https://docs.nfh.global/finternet/overview/actors) Last updated 1 month ago Was this helpful? * [1\. Token State Plane](https://docs.nfh.global/finternet/overview/how-it-works#id-1.-token-state-plane) * [Native Mode](https://docs.nfh.global/finternet/overview/how-it-works#native-mode) * [Proxy Mode](https://docs.nfh.global/finternet/overview/how-it-works#proxy-mode) * [Commitments](https://docs.nfh.global/finternet/overview/how-it-works#commitments) * [2\. Policy Enforcement Plane](https://docs.nfh.global/finternet/overview/how-it-works#id-2.-policy-enforcement-plane) * [Token Programs](https://docs.nfh.global/finternet/overview/how-it-works#token-programs) * [Pre/Post Hooks](https://docs.nfh.global/finternet/overview/how-it-works#pre-post-hooks) * [Compliance Rules](https://docs.nfh.global/finternet/overview/how-it-works#compliance-rules) * [3\. Identity and Credential Plane](https://docs.nfh.global/finternet/overview/how-it-works#id-3.-identity-and-credential-plane) * [Finternet Accounts](https://docs.nfh.global/finternet/overview/how-it-works#finternet-accounts) * [Registry](https://docs.nfh.global/finternet/overview/how-it-works#registry) * [Verifiable Credentials](https://docs.nfh.global/finternet/overview/how-it-works#verifiable-credentials) * [How the Planes Interact](https://docs.nfh.global/finternet/overview/how-it-works#how-the-planes-interact) Was this helpful? --- # Glossary | Finternet | NFH Fabric Canonical definitions for terms used throughout the Finternet documentation. ### [](https://docs.nfh.global/finternet/overview/glossary#account) Account A Finternet identity representing a human or legal entity. Identified by a UUIDv7 address and a DID. An account can hold tokens across multiple token pools and is controlled by one or more cryptographic key pairs. ### [](https://docs.nfh.global/finternet/overview/glossary#adapter) Adapter A bridge between UNITS and an external ledger (e.g., Ethereum, Solana, a private database). Adapters translate external state into UNITS-compatible representations, enabling proxy mode. ### [](https://docs.nfh.global/finternet/overview/glossary#allocation) Allocation The quantity of a token held by a specific identity within a token pool. An allocation is part of a toket (token account). ### [](https://docs.nfh.global/finternet/overview/glossary#commitment) Commitment A cryptographic hash proving the state of a token at a point in time. Per-token commitments use SHA-256 chaining; block-level commitments use BLAKE3 Merkle trees. Users can independently verify commitments without trusting UNITS. ### [](https://docs.nfh.global/finternet/overview/glossary#delegation) Delegation A scoped grant of permission from one account to another. Delegations are defined by label (which tokens), permission level (view, transact, manage), rule type (allow or deny), and optionally an expiration. Delegations are enforced by the OPA-based RBAC engine. ### [](https://docs.nfh.global/finternet/overview/glossary#developer-token) Developer Token An API key issued to an API client. Used for authenticating API requests. The key is hashed (SHA-256) before storage; the plaintext is shown exactly once at creation time. ### [](https://docs.nfh.global/finternet/overview/glossary#did-decentralized-identifier) DID (Decentralized Identifier) A W3C-standard identifier (`did:web`) associated with a Finternet account. Publicly verifiable. Used for zero-trust identity verification. ### [](https://docs.nfh.global/finternet/overview/glossary#hook) Hook A lifecycle callback attached to a token class. Pre-hooks validate before an operation (and can reject it). Post-hooks execute after an operation succeeds. Hooks are how token managers enforce business rules. ### [](https://docs.nfh.global/finternet/overview/glossary#issuer) Issuer The entity whose liability backs a token. The economic owner of the asset β€” a bank, employer, or government. ### [](https://docs.nfh.global/finternet/overview/glossary#label) Label A scoping mechanism for delegations. Labels can target a specific token (`token:{id}`), all tokens of a class (`tokenclass:{id}`), or a user-defined tag. Labels determine which tokens a delegation applies to. ### [](https://docs.nfh.global/finternet/overview/glossary#native-mode) Native Mode The state mode where UNITS is the authoritative source of truth for a token. UNITS maintains the complete allocation history and generates commitments. ### [](https://docs.nfh.global/finternet/overview/glossary#proxy-mode) Proxy Mode The state mode where an external ledger is the authoritative source of truth. UNITS maintains a read-shadow via adapters and provides a unified view and policy layer on top. ### [](https://docs.nfh.global/finternet/overview/glossary#restate) Restate A durable workflow execution engine used by UNITS for multi-step operations (e.g., delegation approval workflows). Provides exactly-once execution guarantees and durable promises. ### [](https://docs.nfh.global/finternet/overview/glossary#token) Token A digital representation of value or a right, held within a token pool. Tokens can represent fungible assets (money, points), non-fungible assets (deeds, certificates), or credentials. ### [](https://docs.nfh.global/finternet/overview/glossary#token-class) Token Class A registered type of token with a defined schema, hook configuration, metadata, and compliance rules. All tokens of a class share the same token program and policy configuration. ### [](https://docs.nfh.global/finternet/overview/glossary#token-manager) Token Manager The operator of a token pool. Manages issuance, enforces class-level policies, and can veto operations via hooks. Must be institutionally distinct from the UNITS operator. ### [](https://docs.nfh.global/finternet/overview/glossary#token-pool) Token Pool The complete ownership distribution of a token class at all points in time. A token pool contains all tokets (token accounts) for a given class, along with their historical state. ### [](https://docs.nfh.global/finternet/overview/glossary#token-program) Token Program A pluggable Rust implementation that defines the behaviour of token operations (mint, burn, transfer, freeze, lock, etc.). Each token class is associated with a token program. ### [](https://docs.nfh.global/finternet/overview/glossary#toket-token-account) Toket (Token Account) A user-level container within a token pool. Contains the allocation (quantity), dependency pointers (references to credentials or other tokens), policy rules, and metadata. ### [](https://docs.nfh.global/finternet/overview/glossary#trust-provider) Trust Provider An entity that issues Verifiable Credentials (KYC, accreditation, compliance). Registered in a trust registry per jurisdiction. ### [](https://docs.nfh.global/finternet/overview/glossary#units) UNITS Unified Information Tokenisation System. The core implementation of the Finternet protocol. Provides the token state plane, policy enforcement plane, and identity/credential plane. ### [](https://docs.nfh.global/finternet/overview/glossary#verifiable-credential-vc) Verifiable Credential (VC) A W3C-standard credential issued by a Trust Provider and bound to a Finternet account. Used for compliance enforcement at transfer time (e.g., KYC, accredited investor status). [PreviousHow Finternet Compares](https://docs.nfh.global/finternet/overview/comparison) [NextAccounts and Identity](https://docs.nfh.global/finternet/concepts/accounts-and-identity) Last updated 1 month ago Was this helpful? * [Account](https://docs.nfh.global/finternet/overview/glossary#account) * [Adapter](https://docs.nfh.global/finternet/overview/glossary#adapter) * [Allocation](https://docs.nfh.global/finternet/overview/glossary#allocation) * [Commitment](https://docs.nfh.global/finternet/overview/glossary#commitment) * [Delegation](https://docs.nfh.global/finternet/overview/glossary#delegation) * [Developer Token](https://docs.nfh.global/finternet/overview/glossary#developer-token) * [DID (Decentralized Identifier)](https://docs.nfh.global/finternet/overview/glossary#did-decentralized-identifier) * [Hook](https://docs.nfh.global/finternet/overview/glossary#hook) * [Issuer](https://docs.nfh.global/finternet/overview/glossary#issuer) * [Label](https://docs.nfh.global/finternet/overview/glossary#label) * [Native Mode](https://docs.nfh.global/finternet/overview/glossary#native-mode) * [Proxy Mode](https://docs.nfh.global/finternet/overview/glossary#proxy-mode) * [Restate](https://docs.nfh.global/finternet/overview/glossary#restate) * [Token](https://docs.nfh.global/finternet/overview/glossary#token) * [Token Class](https://docs.nfh.global/finternet/overview/glossary#token-class) * [Token Manager](https://docs.nfh.global/finternet/overview/glossary#token-manager) * [Token Pool](https://docs.nfh.global/finternet/overview/glossary#token-pool) * [Token Program](https://docs.nfh.global/finternet/overview/glossary#token-program) * [Toket (Token Account)](https://docs.nfh.global/finternet/overview/glossary#toket-token-account) * [Trust Provider](https://docs.nfh.global/finternet/overview/glossary#trust-provider) * [UNITS](https://docs.nfh.global/finternet/overview/glossary#units) * [Verifiable Credential (VC)](https://docs.nfh.global/finternet/overview/glossary#verifiable-credential-vc) Was this helpful? --- # The Actor Model | Finternet | NFH Fabric Finternet defines six logical roles that interact within the protocol. Understanding these roles is essential for knowing where you fit and what you can build. spinner [](https://docs.nfh.global/finternet/overview/actors#id-1.-end-user) 1\. End User -------------------------------------------------------------------------------------- The human or legal entity with a Finternet account. End users hold tokens across multiple token managers via a single account address. **What they do:** * Hold and transfer tokens * View unified holdings across native and proxy pools * Delegate authority to Apps and Agents (scoped by token class, amount, frequency, and time) * Verify their own token state via commitment proofs **Interface:** Finternet App (primary), Account Owner API [](https://docs.nfh.global/finternet/overview/actors#id-2.-app) 2\. App ---------------------------------------------------------------------------- A third-party or first-party application that acts on behalf of an End User. Apps receive delegation credentials bounded by scope. **What they do:** * Perform token operations within delegated scope * Cannot exceed the delegation granted by the user * Can further delegate to sub-agents (scope can only narrow, never widen) **Key constraint:** Apps authenticate via API keys (developer tokens) and operate within the RBAC system. Their allowed operations are defined by client scopes and delegation rules. **Interface:** App API with developer tokens [](https://docs.nfh.global/finternet/overview/actors#id-3.-issuer) 3\. Issuer ---------------------------------------------------------------------------------- The entity whose liability backs a token. An issuer is the economic owner β€” the bank behind a tokenised deposit, the employer behind a corporate voucher, the government behind a digital credential. **What they do:** * Define token class parameters (schema, hooks, metadata, compliance rules) * Register token classes with a Token Manager * Mint tokens (native issuance) or register existing external tokens (proxy issuance) * May delegate operational management to a Token Manager **Interface:** UNITS API (token class registration, mint operations) [](https://docs.nfh.global/finternet/overview/actors#id-4.-token-manager) 4\. Token Manager ------------------------------------------------------------------------------------------------ The operator that maintains an authoritative token pool for one or more token classes. A Token Manager enforces issuance and transfer rules, and can receive lifecycle event notifications. **What they do:** * Manage the token pool: monitor allocations, handle lifecycle events * Enforce class-level policies (which operations are allowed, who can perform them) * Configure pre/post hooks for their token classes * Veto transfers via pre-hooks * Operate within a jurisdictional trust domain **Key constraint:** The Token Manager must be institutionally distinct from the UNITS operator (governance separation). **Interface:** UNITS API (pool management, hook configuration), webhook/callback interface for lifecycle events [](https://docs.nfh.global/finternet/overview/actors#id-5.-trust-provider) 5\. Trust Provider -------------------------------------------------------------------------------------------------- An entity that issues Verifiable Credentials β€” KYC attestations, accreditation certificates, compliance proofs. **What they do:** * Issue credentials bound to Finternet accounts * Provide attestations and trust services (custodian, guarantor, verifier) * Register in a trust registry per jurisdiction **Interface:** Finternet Credential API (issuance, revocation, lookup), Trust Provider Registry [](https://docs.nfh.global/finternet/overview/actors#id-6.-units) 6\. UNITS -------------------------------------------------------------------------------- The core system that implements the Finternet protocol. UNITS maintains token state (native and proxy), enforces policies, and manages identity and registry. **What it provides:** * REST API for all token, account, and registry operations * Async event processing via Kafka for token operations * Token programs (Rust) for programmable asset behaviour * Commitment engine for tamper-evident state proofs * Adapter orchestration for bridging external ledgers * RBAC and delegation engine for access control * Workflow orchestration (via Restate) for multi-step operations **Key constraint:** UNITS is a trusted operator within its operational boundary. It is not a blockchain β€” it does not claim censorship resistance or global consensus. Its trust model is institutional, backed by cryptographic commitments that users can independently verify. **Interface:** REST API (envelope pattern), Kafka event streams, Restate workflow orchestration [PreviousHow It Works: The Three Planes](https://docs.nfh.global/finternet/overview/how-it-works) [NextHow Finternet Compares](https://docs.nfh.global/finternet/overview/comparison) Last updated 1 month ago Was this helpful? * [1\. End User](https://docs.nfh.global/finternet/overview/actors#id-1.-end-user) * [2\. App](https://docs.nfh.global/finternet/overview/actors#id-2.-app) * [3\. Issuer](https://docs.nfh.global/finternet/overview/actors#id-3.-issuer) * [4\. Token Manager](https://docs.nfh.global/finternet/overview/actors#id-4.-token-manager) * [5\. Trust Provider](https://docs.nfh.global/finternet/overview/actors#id-5.-trust-provider) * [6\. UNITS](https://docs.nfh.global/finternet/overview/actors#id-6.-units) Was this helpful? --- # Accounts and Identity | Finternet | NFH Fabric Understanding the identity model is foundational to building on Finternet. This page covers how users are identified, authenticated, and authorised. [](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-address-a-self-sovereign-controller) The Address: A Self-Sovereign Controller ---------------------------------------------------------------------------------------------------------------------------------------------------------- An **Address** is the root of a user's identity on Finternet. It represents a controlling entity β€” an individual or a business β€” that can own resources and authorise actions. * **Cryptographic Foundation:** Each address is controlled by a master key pair generated on the client's device using MPC (Multi-Party Computation) via [Silence Laboratories](https://silencelaboratories.com/) . Keys support both secp256k1 (EVM-compatible) and ed25519 (Solana-compatible) curves. * **Controller, Not a Wallet:** An address itself does not hold tokens. It is the entity that _controls_ one or more accounts and their token holdings. * **Passkey-Based Recovery:** Addresses are bound to device passkeys (WebAuthn), enabling biometric authentication and multi-device recovery without seed phrases. [](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-account-a-universal-asset-container) The Account: A Universal Asset Container ---------------------------------------------------------------------------------------------------------------------------------------------------------- An **Account** is a versatile container for digital assets. It is owned and controlled by one or more addresses. * **Universal by Design:** Accounts can hold any type of digital asset β€” fungible tokens (stablecoins, deposits), non-fungible tokens (deeds, certificates), and credentials. * **Multi-Signature Ready:** An account can be controlled by multiple addresses, enabling joint personal accounts, corporate accounts with different roles, and multi-party governance. * **Unified View:** A single account aggregates holdings across all token pools (native and proxy) into one view. spinner [](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-dual-identifier-system) The Dual Identifier System ------------------------------------------------------------------------------------------------------------------------------- Every address is represented by two distinct identifiers: Identifier Format Purpose **DID** `did:web:...` Public, verifiable identity. W3C standard. Used for zero-trust verification β€” anyone can verify signatures without trusting the database. **Account ID** UUIDv7 Internal primary key. Time-sortable, optimised for high-performance database operations at scale. This separation lets the system be cryptographically robust in public interactions and highly efficient in internal operations. [](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-dual-security-model) The Dual Security Model ------------------------------------------------------------------------------------------------------------------------- API security is progressive β€” friction is applied only when the operation warrants it. ### [](https://docs.nfh.global/finternet/concepts/accounts-and-identity#jwt-session-access) JWT (Session Access) A standard JSON Web Token proves _who the user is_. Issued by Keycloak (OIDC) after authentication. Sufficient for low-risk operations like reading data, listing tokens, or checking balances. ### [](https://docs.nfh.global/finternet/concepts/accounts-and-identity#jws-action-signing) JWS (Action Signing) For critical operations β€” transferring tokens, modifying delegations, adding account members β€” the request payload must be cryptographically signed with the user's private key. This provides non-repudiable proof that the user _authorised a specific action_. [](https://docs.nfh.global/finternet/concepts/accounts-and-identity#key-management) Key Management ------------------------------------------------------------------------------------------------------- Finternet uses MPC (Multi-Party Computation) for key generation and signing, provided by [Silence Laboratories](https://silencelaboratories.com/) : * **Key Generation:** Split-key generation across multiple parties. No single party ever holds the complete private key. * **Signing:** Threshold signatures β€” a configurable subset of parties must cooperate to produce a valid signature. * **Supported Curves:** secp256k1 (Ethereum/EVM) and ed25519 (Solana). * **Passkey Binding:** Keys are bound to device passkeys for biometric authentication. Users authenticate with fingerprint or face ID, not passwords or seed phrases. [](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-registry) The Registry --------------------------------------------------------------------------------------------------- The registry maps human-readable identifiers to Finternet accounts: * **Email lookup** β€” given an email, resolve to the account address (emails are hashed before storage) * **Phone lookup** β€” given a phone number, resolve to the account address * **DID lookup** β€” given a DID, resolve to the account address * **Public key lookup** β€” given an EVM or Solana public key, resolve to the account address Private lookups (email, phone) require authentication and a legitimate need. DID and public key lookups are available to authenticated API clients. [PreviousGlossary](https://docs.nfh.global/finternet/overview/glossary) [NextTokens and Token Pools](https://docs.nfh.global/finternet/concepts/tokens-and-tokenpools) Last updated 1 month ago Was this helpful? * [The Address: A Self-Sovereign Controller](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-address-a-self-sovereign-controller) * [The Account: A Universal Asset Container](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-account-a-universal-asset-container) * [The Dual Identifier System](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-dual-identifier-system) * [The Dual Security Model](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-dual-security-model) * [JWT (Session Access)](https://docs.nfh.global/finternet/concepts/accounts-and-identity#jwt-session-access) * [JWS (Action Signing)](https://docs.nfh.global/finternet/concepts/accounts-and-identity#jws-action-signing) * [Key Management](https://docs.nfh.global/finternet/concepts/accounts-and-identity#key-management) * [The Registry](https://docs.nfh.global/finternet/concepts/accounts-and-identity#the-registry) Was this helpful? GitBook AssistantAskCopy Low risk (read): JWT in Authorization header High risk (write): JWT + JWS signature in request body --- # Policy and Compliance | Finternet | NFH Fabric Finternet embeds compliance logic into the infrastructure rather than bolting it on at the application layer. This page covers how policies are defined, enforced, and composed. [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#policy-enforcement-architecture) Policy Enforcement Architecture ----------------------------------------------------------------------------------------------------------------------------------------- Policies are enforced at multiple layers: GitBook AssistantAskCopy β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ RBAC Engine (OPA) β”‚ ← Who can do what (scopes, delegations) β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Token Class Policies β”‚ ← What operations are allowed on this class β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Pre/Post Hooks β”‚ ← Business rules per operation β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Token Program Validators β”‚ ← Structural invariants β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ### [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#layer-1-rbac-engine) Layer 1: RBAC Engine The OPA (Open Policy Agent)-based engine evaluates **who** can perform **what** on **which** resource. It considers: * Is the caller the token owner? * Is the caller the token class manager (issuer)? * Does the caller have an active delegation for this resource? * Are there any explicit deny rules? * Does the caller's API client have the required scope? See [Delegation and RBAC](https://docs.nfh.global/finternet/concepts/delegation-and-rbac) for details. ### [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#layer-2-token-class-policies) Layer 2: Token Class Policies Token class managers can define: * **Allowed operations** β€” which operations (transfer, freeze, lock) are permitted for this class * **Manager operations** β€” operations that only the class manager can perform * **User operations** β€” operations that token holders can perform These are evaluated by the RBAC engine's resource input. ### [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#layer-3-pre-post-hooks) Layer 3: Pre/Post Hooks Hooks are the primary mechanism for custom business logic. Pre-hooks can reject operations; post-hooks trigger side effects. See [Token Programs](https://docs.nfh.global/finternet/concepts/token-programs) for details on hook configuration. ### [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#layer-4-token-program-validators) Layer 4: Token Program Validators Validators enforce structural invariants that should never be bypassed β€” the token exists, the caller has the right identity role, the operation is valid for the current state. These are part of the token program itself. [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#compliance-patterns) Compliance Patterns ----------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#credential-gated-transfers) Credential-Gated Transfers Token classes can require that the recipient hold specific credentials before accepting a transfer. The `credential-verification` pre-hook checks for required credentials in the token's dependency pointers. **Example:** A security token requires an "accredited investor" credential. The pre-hook verifies the recipient's credential before allowing the transfer. ### [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#category-level-spending-controls) Category-Level Spending Controls For semi-fungible tokens like corporate vouchers, the token metadata can carry spending restrictions: The token program validates each transaction against these limits. ### [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#time-based-restrictions) Time-Based Restrictions Tokens can carry expiration dates, vesting schedules, or time-locked transfer windows. Pre-hooks evaluate time-based conditions before allowing operations. ### [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#amount-based-restrictions) Amount-Based Restrictions Pre-hooks can enforce: * **Maximum supply** β€” No more than N tokens can exist in a pool * **Minimum balance** β€” A token holder must retain at least M units after any transfer * **Transaction limits** β€” No single transfer can exceed a threshold [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#jurisdictional-rules) Jurisdictional Rules ------------------------------------------------------------------------------------------------------------------- Token classes can be scoped to specific jurisdictions. Jurisdictional rules define: * Which Trust Providers are recognised for KYC in this jurisdiction * What transfer restrictions apply (e.g., cross-border limits) * What reporting obligations are triggered by transfers Jurisdictional rules are enforced through the hook system β€” the token class configures jurisdiction-aware hooks that evaluate the relevant rules at transfer time. [](https://docs.nfh.global/finternet/concepts/policy-and-compliance#audit-trail) Audit Trail ------------------------------------------------------------------------------------------------- Every token operation is recorded with: * **Transaction ID** β€” unique, time-sortable identifier * **Caller identity** β€” which account initiated the operation * **Operation type** β€” mint, transfer, burn, etc. * **Timestamp** β€” when the operation was processed * **Commitment** β€” cryptographic hash of the resulting state * **Hook results** β€” which hooks ran and their outcomes This creates a complete, tamper-evident audit trail for every asset in the system. [PreviousCommitments and Proofs](https://docs.nfh.global/finternet/concepts/commitments-and-proofs) [NextDelegation and RBAC](https://docs.nfh.global/finternet/concepts/delegation-and-rbac) Last updated 1 month ago Was this helpful? * [Policy Enforcement Architecture](https://docs.nfh.global/finternet/concepts/policy-and-compliance#policy-enforcement-architecture) * [Layer 1: RBAC Engine](https://docs.nfh.global/finternet/concepts/policy-and-compliance#layer-1-rbac-engine) * [Layer 2: Token Class Policies](https://docs.nfh.global/finternet/concepts/policy-and-compliance#layer-2-token-class-policies) * [Layer 3: Pre/Post Hooks](https://docs.nfh.global/finternet/concepts/policy-and-compliance#layer-3-pre-post-hooks) * [Layer 4: Token Program Validators](https://docs.nfh.global/finternet/concepts/policy-and-compliance#layer-4-token-program-validators) * [Compliance Patterns](https://docs.nfh.global/finternet/concepts/policy-and-compliance#compliance-patterns) * [Credential-Gated Transfers](https://docs.nfh.global/finternet/concepts/policy-and-compliance#credential-gated-transfers) * [Category-Level Spending Controls](https://docs.nfh.global/finternet/concepts/policy-and-compliance#category-level-spending-controls) * [Time-Based Restrictions](https://docs.nfh.global/finternet/concepts/policy-and-compliance#time-based-restrictions) * [Amount-Based Restrictions](https://docs.nfh.global/finternet/concepts/policy-and-compliance#amount-based-restrictions) * [Jurisdictional Rules](https://docs.nfh.global/finternet/concepts/policy-and-compliance#jurisdictional-rules) * [Audit Trail](https://docs.nfh.global/finternet/concepts/policy-and-compliance#audit-trail) Was this helpful? GitBook AssistantAskCopy { "category_limits": { "electronics": 3000, "office_supplies": 2000 } } --- # Token Operations | Finternet | NFH Fabric The examples below call the hosted UNITS API via `$UNITS_BASE_URL` and `$UNITS_DEVELOPER_TOKEN`. Export these once as shown in [Environment Setup](https://docs.nfh.global/finternet/building/environment-setup) before running any snippet. This page covers how to search, display, and operate on tokens from your application. [](https://docs.nfh.global/finternet/app-developer-guide/token-operations#searching-tokens) Searching Tokens ----------------------------------------------------------------------------------------------------------------- Retrieve tokens for a user β€” the unified view across native and proxy holdings: GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/search \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.search", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "owner_address": "USER_ADDRESS" } }' The response includes both native tokens (held in UNITS) and proxy tokens (shadowed from external ledgers). Each token includes its class information, allocation, metadata, and identity roles. ### [](https://docs.nfh.global/finternet/app-developer-guide/token-operations#filtering) Filtering You can filter by: * **Token class** β€” Show only tokens of a specific class * **Status** β€” Active, frozen, locked * **Tags** β€” Custom labels attached to tokens ### [](https://docs.nfh.global/finternet/app-developer-guide/token-operations#delegated-access) Delegated Access If your app has a delegation from the user, you can also see tokens where the user has granted you `view` permission. Tokens with an "access" identity for your account appear in search results. [](https://docs.nfh.global/finternet/app-developer-guide/token-operations#transferring-tokens) Transferring Tokens ----------------------------------------------------------------------------------------------------------------------- Initiate a transfer on behalf of a user: Transfers require both the user's JWT and a JWS signature (since transfers are high-risk operations). The RBAC engine verifies: 1. The API client has `tokens:create` scope 2. The user is the token owner, or has a `transact` delegation 3. Pre-hooks pass (balance check, compliance rules) ### [](https://docs.nfh.global/finternet/app-developer-guide/token-operations#delegation-on-transfer) Delegation on Transfer When a token is transferred to a new owner, all delegations from the previous owner are **automatically revoked**. The new owner starts with a clean delegation slate. This prevents stale access from persisting after ownership changes. [](https://docs.nfh.global/finternet/app-developer-guide/token-operations#displaying-the-unified-view) Displaying the Unified View --------------------------------------------------------------------------------------------------------------------------------------- To show a user their complete holdings: 1. **Search native tokens** by owner address 2. **Search proxy tokens** by owner address 3. **Merge and group** by token class for display 4. **Show metadata** β€” each token carries rich metadata defined by its class schema The Finternet App (reference implementation) demonstrates this pattern in its portfolio view. [](https://docs.nfh.global/finternet/app-developer-guide/token-operations#transaction-tracking) Transaction Tracking ------------------------------------------------------------------------------------------------------------------------- All token operations are asynchronous. After initiating an operation, poll the transaction status: Status Meaning `submitted` Received, queued for processing `processing` Token Engine is executing the operation `successful` Operation completed `failed` Operation failed β€” check error details [PreviousAccount Integration](https://docs.nfh.global/finternet/app-developer-guide/account-integration) [NextProof Verification](https://docs.nfh.global/finternet/app-developer-guide/proof-verification) Last updated 1 month ago Was this helpful? * [Searching Tokens](https://docs.nfh.global/finternet/app-developer-guide/token-operations#searching-tokens) * [Filtering](https://docs.nfh.global/finternet/app-developer-guide/token-operations#filtering) * [Delegated Access](https://docs.nfh.global/finternet/app-developer-guide/token-operations#delegated-access) * [Transferring Tokens](https://docs.nfh.global/finternet/app-developer-guide/token-operations#transferring-tokens) * [Delegation on Transfer](https://docs.nfh.global/finternet/app-developer-guide/token-operations#delegation-on-transfer) * [Displaying the Unified View](https://docs.nfh.global/finternet/app-developer-guide/token-operations#displaying-the-unified-view) * [Transaction Tracking](https://docs.nfh.global/finternet/app-developer-guide/token-operations#transaction-tracking) Was this helpful? GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/transfer \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.transfer", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN", "user_jwt": "USER_JWT" }, "payload": { "token_id": "TOKEN_ID", "from_address": "SENDER_ADDRESS", "to_address": "RECIPIENT_ADDRESS", "amount": 100 }, "signature": { "type": "JsonWebSignature2020", "jws": "USER_JWS_SIGNATURE" } }' GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/transaction/status \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.transaction.status", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "transaction_id": "TRANSACTION_ID" } }' --- # Environment Setup | Finternet | NFH Fabric Token-program authors, schema authors, and app builders use the **hosted Foundry environment** β€” there is no local UNITS stack to run. Foundry exposes the full Finternet API (accounts, tokens, registry, delegations, key management) behind a single base URL. This page tells you how to get access and point your client at the right endpoint. [](https://docs.nfh.global/finternet/building/environment-setup#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------- **Foundry access** A developer token issued by the Finternet team **HTTP client** `curl`, Postman, or any language SDK **JSON** All requests and responses use a standard envelope There is no Docker, Postgres, Kafka, Keycloak, or Vault to run on your machine. Foundry is a hosted service β€” you only need an API client. [](https://docs.nfh.global/finternet/building/environment-setup#get-access-to-foundry) Get Access to Foundry ----------------------------------------------------------------------------------------------------------------- Foundry access is provisioned by the Finternet engineering team. 1 #### [](https://docs.nfh.global/finternet/building/environment-setup#request-a-developer-account) Request a developer account Email [**\[emailΒ protected\]**](https://docs.nfh.global/cdn-cgi/l/email-protection#5d38333a343338382f34333a1d3b343329382f333829733432) with: * Your name and organisation * A short description of what you plan to build (token programs, schemas, or an application) * The environments you need (development, staging) The team will create a developer account and return the details you need to authenticate. 2 #### [](https://docs.nfh.global/finternet/building/environment-setup#receive-your-credentials) Receive your credentials You will receive: * A **developer token** β€” the B2B API key used in `context.developerToken` * The **Foundry base URL** for the environment you were granted * A link to the OpenAPI reference and any environment-specific notes 3 #### [](https://docs.nfh.global/finternet/building/environment-setup#register-an-end-user-account) Register an end-user account Most endpoints also need an **end-user JWT** in `context.authorization`. Create a Finternet account via `/v1/account/create` using your developer token, then log in through `/v1/account/login` to obtain the user session JWT. See [Authentication](https://docs.nfh.global/finternet/building/authentication) for the full envelope and token flow. [](https://docs.nfh.global/finternet/building/environment-setup#environments) Environments ----------------------------------------------------------------------------------------------- Environment Base URL Purpose **Development** _To be disclosed_ Day-to-day integration work against the latest Foundry build **Staging** _To be disclosed_ Pre-release validation, stable schemas, longer data retention Base URLs are shared privately with each developer when access is granted. Do not hard-code URLs from screenshots or examples β€” always use the values in your onboarding email. [](https://docs.nfh.global/finternet/building/environment-setup#configuration) Configuration ------------------------------------------------------------------------------------------------- Set these two values in your client β€” everything else is driven by the request envelope. Variable Description `UNITS_BASE_URL` The Foundry API base URL for your environment `UNITS_DEVELOPER_TOKEN` The developer token from your onboarding email Example shell setup: [](https://docs.nfh.global/finternet/building/environment-setup#verify-your-access) Verify Your Access ----------------------------------------------------------------------------------------------------------- A simple health check confirms that your token reaches Foundry. A `200 OK` response means Foundry is reachable. If you get `401` on authenticated endpoints, re-check the developer token and that you included the end-user JWT where required. [](https://docs.nfh.global/finternet/building/environment-setup#whats-next) What's Next -------------------------------------------------------------------------------------------- [](https://docs.nfh.global/finternet/building/quickstart) **Quickstart** Walk through a full flow β€” create account, mint, transfer, verify β€” against Foundry [](https://docs.nfh.global/finternet/building/authentication) **Authentication** Developer tokens, JWTs, and the envelope format [](https://docs.nfh.global/finternet/building/api-clients) **API Clients** How clients, keys, and scopes are organised in Foundry [PreviousQuickstart](https://docs.nfh.global/finternet/building/quickstart) [NextAuthentication](https://docs.nfh.global/finternet/building/authentication) Last updated 1 month ago Was this helpful? * [Prerequisites](https://docs.nfh.global/finternet/building/environment-setup#prerequisites) * [Get Access to Foundry](https://docs.nfh.global/finternet/building/environment-setup#get-access-to-foundry) * [Environments](https://docs.nfh.global/finternet/building/environment-setup#environments) * [Configuration](https://docs.nfh.global/finternet/building/environment-setup#configuration) * [Verify Your Access](https://docs.nfh.global/finternet/building/environment-setup#verify-your-access) * [What's Next](https://docs.nfh.global/finternet/building/environment-setup#whats-next) Was this helpful? GitBook AssistantAskCopy export UNITS_BASE_URL="https://" export UNITS_DEVELOPER_TOKEN="dev-token-..." GitBook AssistantAskCopy curl -s "$UNITS_BASE_URL/health" --- # Programmable Payments | Finternet | NFH Fabric This use case demonstrates how Finternet's delegation system and token programs enable conditional, recurring, and escrow payments β€” without requiring custom middleware. [](https://docs.nfh.global/finternet/use-cases/programmable-payments#the-problem) The Problem -------------------------------------------------------------------------------------------------- Payments today are either manual (user initiates each one) or automated but rigid (standing orders with no conditions). There is no standard way to express "pay X if Y happens" at the infrastructure level. [](https://docs.nfh.global/finternet/use-cases/programmable-payments#programmable-payment-patterns) Programmable Payment Patterns -------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/finternet/use-cases/programmable-payments#id-1.-recurring-payments-via-delegation) 1\. Recurring Payments via Delegation A user delegates `transact` permission to a subscription service, scoped to a specific token class and amount limit. GitBook AssistantAskCopy Delegation: grantor: user_alice grantee: subscription_app label: tokenclass:TDEP (tokenised deposits) permission: transact expires_at: 2027-01-01 The subscription app can now initiate transfers from Alice's account β€” but only of `TDEP` tokens, and only within the delegated scope. Alice can revoke at any time. **Flow:** 1. Each month, the subscription app calls the transfer API using its developer token 2. The RBAC engine validates: active delegation, correct label, correct permission 3. The transfer executes within Alice's deposit tokens 4. Alice sees the transaction in her history with full commitment proof ### [](https://docs.nfh.global/finternet/use-cases/programmable-payments#id-2.-conditional-release-escrow) 2\. Conditional Release (Escrow) A buyer locks tokens with a release condition. The tokens are visible but untransferable until the condition is met. **Flow:** 1. Buyer mints or designates tokens for the purchase 2. Buyer locks the tokens with metadata specifying the release condition: 3. Seller ships the goods 4. Upon delivery confirmation, the token manager (or a workflow) unlocks and transfers the tokens to the seller The lock operation is enforced by the Token Engine β€” no one can transfer locked tokens, not even the owner. Only the authorized unlocker can release them. ### [](https://docs.nfh.global/finternet/use-cases/programmable-payments#id-3.-multi-party-approval) 3\. Multi-Party Approval For high-value payments, require multiple parties to approve before execution. **Flow:** 1. A corporate account has multiple controlling addresses (multi-sig) 2. Payment initiation requires JWS signatures from a threshold of controllers 3. A Restate workflow collects signatures (similar to delegation approval) 4. Once the threshold is met, the transfer executes ### [](https://docs.nfh.global/finternet/use-cases/programmable-payments#id-4.-delivery-vs-payment-dvp) 4\. Delivery-vs-Payment (DvP) Atomic exchange of a payment token for a delivery token. **Flow:** 1. Buyer locks payment tokens (escrow) 2. Seller locks delivery tokens (proof of goods) 3. A workflow verifies both locks are in place 4. Atomic swap: payment goes to seller, delivery goes to buyer 5. If either party defaults, locks are released back to original owners [](https://docs.nfh.global/finternet/use-cases/programmable-payments#building-these-patterns) Building These Patterns -------------------------------------------------------------------------------------------------------------------------- All of these patterns use existing Finternet primitives: Primitive Used For **Delegation** Recurring payments, subscription billing, agent-initiated payments **Lock/Unlock** Escrow, conditional release, collateral **Multi-sig** Corporate approvals, joint account operations **Restate Workflows** Multi-step approval flows, DvP orchestration **Pre-hooks** Condition validation before any operation **Post-hooks** Notifications, downstream triggers after operations **Commitment proofs** Audit trail for every payment No custom middleware is needed β€” the programmability is at the infrastructure layer. [PreviousLoans and Securitisation](https://docs.nfh.global/finternet/use-cases/loans-and-securitisation) [NextArchitecture](https://docs.nfh.global/finternet/architecture/architecture) Last updated 1 month ago Was this helpful? * [The Problem](https://docs.nfh.global/finternet/use-cases/programmable-payments#the-problem) * [Programmable Payment Patterns](https://docs.nfh.global/finternet/use-cases/programmable-payments#programmable-payment-patterns) * [1\. Recurring Payments via Delegation](https://docs.nfh.global/finternet/use-cases/programmable-payments#id-1.-recurring-payments-via-delegation) * [2\. Conditional Release (Escrow)](https://docs.nfh.global/finternet/use-cases/programmable-payments#id-2.-conditional-release-escrow) * [3\. Multi-Party Approval](https://docs.nfh.global/finternet/use-cases/programmable-payments#id-3.-multi-party-approval) * [4\. Delivery-vs-Payment (DvP)](https://docs.nfh.global/finternet/use-cases/programmable-payments#id-4.-delivery-vs-payment-dvp) * [Building These Patterns](https://docs.nfh.global/finternet/use-cases/programmable-payments#building-these-patterns) Was this helpful? GitBook AssistantAskCopy { "lock_reason": "escrow_for_order_123", "release_condition": "delivery_confirmed" } --- # Adapter Integration | Finternet | NFH Fabric The examples below call the hosted UNITS API via `$UNITS_BASE_URL` and `$UNITS_DEVELOPER_TOKEN`. Export these once as shown in [Environment Setup](https://docs.nfh.global/finternet/building/environment-setup) before running any snippet. Adapters bridge UNITS and external ledgers, enabling proxy mode. This page covers how to configure existing adapters and the interface for building custom ones. [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#adapter-architecture) Adapter Architecture ---------------------------------------------------------------------------------------------------------------------------- The **Adapter Orchestrator** routes requests to the appropriate adapter based on chain configuration and priority settings. It provides automatic failover across configured providers. spinner [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#configuring-an-adapter) Configuring an Adapter -------------------------------------------------------------------------------------------------------------------------------- Register an adapter in the UNITS registry: GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/registry/adapters/register \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.registry.adapter.register", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "name": "alchemy-ethereum-mainnet", "adapter_type": "alchemy-evm", "chain": "ethereum-mainnet", "config": { "rpc_url": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY", "ws_url": "wss://eth-mainnet.g.alchemy.com/v2/YOUR_KEY" }, "priority": 1 } }' [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#chain-configuration) Chain Configuration -------------------------------------------------------------------------------------------------------------------------- Register supported chains in the registry: [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#supported-adapters) Supported Adapters ------------------------------------------------------------------------------------------------------------------------ ### [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#alchemy-evm) Alchemy EVM Supports Ethereum and all EVM-compatible chains via Alchemy's API: * **Balance queries** β€” Read token balances for any address * **Transaction submission** β€” Submit signed transactions * **Event monitoring** β€” Watch for Transfer events on token contracts * **Supported chains** β€” Ethereum, Polygon, Arbitrum, Base, Optimism, etc. ### [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#solana) Solana Supports Solana mainnet and devnet: * **SPL token queries** β€” Read token account balances * **Transaction assembly** β€” Build and sign Solana transactions * **Ed25519 signatures** β€” Uses MPC-generated ed25519 keys ### [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#private-ledger) Private Ledger For connecting to internal databases or APIs: * **Authenticated API calls** β€” mTLS, JWT, or HMAC authentication * **Custom data mapping** β€” Configure how external fields map to UNITS token properties * **State proofs** β€” External system must provide signed state proofs for verification [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#adapter-interface) Adapter Interface ---------------------------------------------------------------------------------------------------------------------- If you need to build a custom adapter, implement the following interface: Method Purpose `getBalance(address, contract)` Read token balance for an address `getTokenMetadata(contract)` Read token metadata (name, symbol, decimals) `submitTransaction(signedTx)` Submit a signed transaction `getTransactionStatus(txHash)` Check transaction confirmation status `getEvents(contract, fromBlock)` Read token transfer events [](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#monitoring) Monitoring -------------------------------------------------------------------------------------------------------- The adapter orchestrator exposes health metrics: * **Adapter availability** β€” Which adapters are responding * **Latency** β€” Response times per adapter * **Error rates** β€” Failed requests per adapter * **Failover events** β€” When traffic shifted between adapters [PreviousCustom Token Programs](https://docs.nfh.global/finternet/token-manager-guide/custom-programs) [NextApp Developer Guide](https://docs.nfh.global/finternet/app-developer-guide/app-developer-guide) Last updated 1 month ago Was this helpful? * [Adapter Architecture](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#adapter-architecture) * [Configuring an Adapter](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#configuring-an-adapter) * [Chain Configuration](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#chain-configuration) * [Supported Adapters](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#supported-adapters) * [Alchemy EVM](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#alchemy-evm) * [Solana](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#solana) * [Private Ledger](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#private-ledger) * [Adapter Interface](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#adapter-interface) * [Monitoring](https://docs.nfh.global/finternet/token-manager-guide/adapter-integration#monitoring) Was this helpful? GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/registry/chains/register \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.registry.chain.register", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "name": "Ethereum Mainnet", "chain_id": "1", "network_type": "mainnet", "native_currency": "ETH" } }' --- # State Modes: Native vs Proxy | Finternet | NFH Fabric Every token in Finternet operates in one of two state modes, depending on where the authoritative record lives. Understanding this distinction is essential for choosing the right approach for your use case. [](https://docs.nfh.global/finternet/concepts/state-modes#native-mode) Native Mode --------------------------------------------------------------------------------------- In native mode, **UNITS is the source of truth**. The token's state β€” ownership, allocation, metadata β€” is managed entirely within UNITS. ### [](https://docs.nfh.global/finternet/concepts/state-modes#when-to-use-native-mode) When to Use Native Mode * You are issuing a **new digital asset** (tokenised deposits, vouchers, credentials, loyalty points) * You want **full programmability** β€” pre/post hooks, token programs, compliance rules all enforced by UNITS * You want **commitment proofs** β€” every state change produces a verifiable cryptographic hash * You do not need to reference an external ledger ### [](https://docs.nfh.global/finternet/concepts/state-modes#how-it-works) How It Works 1. **Mint** β€” An issuer creates tokens via the UNITS API. The Token Engine processes the mint operation, creates the token record, and generates the initial commitment. 2. **Transfer** β€” The sender initiates a transfer. Pre-hooks validate (balance, eligibility, credentials). The Token Engine atomically decrements the sender and increments the recipient. A new commitment is generated for both tokens. 3. **Query** β€” Anyone with appropriate access (owner, delegated user, app) can read the token state directly from UNITS. ### [](https://docs.nfh.global/finternet/concepts/state-modes#characteristics) Characteristics Property Value Source of truth UNITS database (PostgreSQL) Commitment proofs Yes β€” SHA-256 per-token, BLAKE3 Merkle blocks Programmability Full β€” token programs + hooks Settlement Immediate (single database transaction) External dependencies None [](https://docs.nfh.global/finternet/concepts/state-modes#proxy-mode) Proxy Mode ------------------------------------------------------------------------------------- In proxy mode, **the authoritative state lives outside UNITS**. The system of record can be any external system β€” a public blockchain, a core banking ledger, a custodian's internal database, or any other source. UNITS maintains a read-shadow β€” a cached representation of that state β€” for unified visibility and policy enforcement. ### [](https://docs.nfh.global/finternet/concepts/state-modes#when-to-use-proxy-mode) When to Use Proxy Mode * You have **existing external assets** that you want to bring into the Finternet unified view. The source can be: * A public blockchain (ERC-20, Solana SPL, Bitcoin UTXOs) * A private or permissioned ledger (CBDC pilot, settlement network) * An institutional system of record (core banking, custodian DB, KYC provider) * You want to apply **Finternet policy rules** (delegation, compliance checks) on top of external assets * You want users to see **all their holdings** β€” native and external β€” in one place ### [](https://docs.nfh.global/finternet/concepts/state-modes#how-it-works-1) How It Works 1. **Register** β€” An issuer registers an existing external token class as a proxy in UNITS. This includes the adapter configuration (which external system, which connector, which sync method). 2. **Sync** β€” The adapter queries the external system and populates the UNITS shadow state. Users see their external holdings alongside native tokens. 3. **Transfer** β€” For proxy tokens, the actual state change happens in the external system. UNITS coordinates the flow: validate via pre-hooks, submit to the external system via the adapter, and update the shadow state on confirmation. ### [](https://docs.nfh.global/finternet/concepts/state-modes#characteristics-1) Characteristics Property Value Source of truth External system (blockchain, private ledger, or institutional database) Commitment proofs External system's finality / authority model Programmability Partial β€” UNITS hooks layer on top of external rules Settlement Depends on the external system (block confirmation, batch close, etc.) External dependencies Adapter + external system availability [](https://docs.nfh.global/finternet/concepts/state-modes#adapters) Adapters --------------------------------------------------------------------------------- Adapters are the bridge between UNITS and external ledgers. They implement a standardised interface for: * **State queries** β€” Read current balances, token metadata, and ownership from the external ledger * **Transaction submission** β€” Submit signed transactions to the external ledger * **Event monitoring** β€” Watch for state changes on the external ledger ### [](https://docs.nfh.global/finternet/concepts/state-modes#supported-adapters) Supported Adapters Adapter Ledger Status Alchemy EVM Ethereum and EVM-compatible chains Available Solana Solana Available Private Ledger Custom databases and APIs Interface specified, implementations vary ### [](https://docs.nfh.global/finternet/concepts/state-modes#adapter-configuration) Adapter Configuration Adapters are registered in the UNITS registry with: * Chain identifier and network (e.g., Ethereum mainnet, Polygon) * RPC endpoint configuration * Contract addresses for token classes * Priority and failover settings (the adapter orchestrator routes requests based on priority) [](https://docs.nfh.global/finternet/concepts/state-modes#choosing-between-native-and-proxy) Choosing Between Native and Proxy ----------------------------------------------------------------------------------------------------------------------------------- Scenario Recommended Mode New tokenised deposit product Native Existing ERC-20 stablecoin Proxy Corporate voucher system Native Solana NFT collection Proxy Digital identity credential Native Multi-chain DeFi portfolio view Proxy (per chain) Bank deposit balance from a core banking system Proxy (private-ledger adapter) Custodian-held off-exchange assets Proxy (custodian-API adapter) Hybrid: new token backed by external collateral Native token with proxy dependency pointer [PreviousToken Programs](https://docs.nfh.global/finternet/concepts/token-programs) [NextCommitments and Proofs](https://docs.nfh.global/finternet/concepts/commitments-and-proofs) Last updated 1 month ago Was this helpful? * [Native Mode](https://docs.nfh.global/finternet/concepts/state-modes#native-mode) * [When to Use Native Mode](https://docs.nfh.global/finternet/concepts/state-modes#when-to-use-native-mode) * [How It Works](https://docs.nfh.global/finternet/concepts/state-modes#how-it-works) * [Characteristics](https://docs.nfh.global/finternet/concepts/state-modes#characteristics) * [Proxy Mode](https://docs.nfh.global/finternet/concepts/state-modes#proxy-mode) * [When to Use Proxy Mode](https://docs.nfh.global/finternet/concepts/state-modes#when-to-use-proxy-mode) * [How It Works](https://docs.nfh.global/finternet/concepts/state-modes#how-it-works-1) * [Characteristics](https://docs.nfh.global/finternet/concepts/state-modes#characteristics-1) * [Adapters](https://docs.nfh.global/finternet/concepts/state-modes#adapters) * [Supported Adapters](https://docs.nfh.global/finternet/concepts/state-modes#supported-adapters) * [Adapter Configuration](https://docs.nfh.global/finternet/concepts/state-modes#adapter-configuration) * [Choosing Between Native and Proxy](https://docs.nfh.global/finternet/concepts/state-modes#choosing-between-native-and-proxy) Was this helpful? --- # Proof Verification | Finternet | NFH Fabric The examples below call the hosted UNITS API via `$UNITS_BASE_URL` and `$UNITS_DEVELOPER_TOKEN`. Export these once as shown in [Environment Setup](https://docs.nfh.global/finternet/building/environment-setup) before running any snippet. One of Finternet's key differentiators is that users can **independently verify** their token state. This page shows how to integrate proof verification into your application. [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#why-verification-matters) Why Verification Matters ----------------------------------------------------------------------------------------------------------------------------------- UNITS is a trusted operator, but "trust but verify" is a core principle. Commitment proofs let users (and your app) confirm that: * The token state has not been tampered with since issuance * The sequence of operations (mint, transfer, update) matches what the user expects * No unauthorised modifications have occurred [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#getting-a-proof) Getting a Proof ----------------------------------------------------------------------------------------------------------------- GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/proof/get \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.proof.get", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_id": "TOKEN_ID" } }' The response includes: * **Current state** β€” the token's current allocation, metadata, and identities * **Commitment chain** β€” the sequence of SHA-256 hashes from genesis to current * **Transaction history** β€” the operations that produced each commitment [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#verifying-a-proof-client-side) Verifying a Proof (Client-Side) ----------------------------------------------------------------------------------------------------------------------------------------------- To verify a proof in your application: [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#getting-a-merkle-proof) Getting a Merkle Proof ------------------------------------------------------------------------------------------------------------------------------- For block-level verification: This returns the Merkle path from the transaction leaf to the block root β€” the sibling hashes needed to reconstruct and verify inclusion. [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#server-side-verification) Server-Side Verification ----------------------------------------------------------------------------------------------------------------------------------- For convenience, UNITS also provides a verification endpoint: This recomputes the commitment and returns whether it matches. However, for true independent verification, client-side computation is recommended β€” it removes UNITS from the trust chain. [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#integration-patterns) Integration Patterns --------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#periodic-audit) Periodic Audit Run proof verification on a schedule (e.g., daily) for all tokens held by your users. Alert on any mismatches. ### [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#on-transfer-verification) On-Transfer Verification Verify the sender's commitment before accepting a transfer. This confirms the token's history is clean. ### [](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#user-facing-verification) User-Facing Verification Show a "verified" badge on tokens where the commitment chain has been independently validated. This builds user trust in the platform. [PreviousToken Operations](https://docs.nfh.global/finternet/app-developer-guide/token-operations) [NextTrust Provider Guide](https://docs.nfh.global/finternet/trust-provider-guide/trust-provider-guide) Last updated 1 month ago Was this helpful? * [Why Verification Matters](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#why-verification-matters) * [Getting a Proof](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#getting-a-proof) * [Verifying a Proof (Client-Side)](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#verifying-a-proof-client-side) * [Getting a Merkle Proof](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#getting-a-merkle-proof) * [Server-Side Verification](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#server-side-verification) * [Integration Patterns](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#integration-patterns) * [Periodic Audit](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#periodic-audit) * [On-Transfer Verification](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#on-transfer-verification) * [User-Facing Verification](https://docs.nfh.global/finternet/app-developer-guide/proof-verification#user-facing-verification) Was this helpful? GitBook AssistantAskCopy const crypto = require('crypto'); function verifyCommitmentChain(commitments) { for (let i = 1; i < commitments.length; i++) { const expected = crypto .createHash('sha256') .update(commitments[i - 1].hash) // previous commitment .update(commitments[i].tx_id) // transaction ID .update(commitments[i].timestamp) // timestamp .update(JSON.stringify(commitments[i].state)) // full state .digest('hex'); if (expected !== commitments[i].hash) { return { valid: false, broken_at: i }; } } return { valid: true }; } GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/proof/leaf \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.proof.leaf", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "transaction_id": "TRANSACTION_ID" } }' GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/proof/verify \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.proof.verify", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_id": "TOKEN_ID", "expected_commitment": "COMMITMENT_HASH" } }' --- # Event Processing | Finternet | NFH Fabric Token operations in UNITS are processed asynchronously via Kafka. This page covers the event pipeline, processing guarantees, and error handling. [](https://docs.nfh.global/finternet/architecture/event-processing#pipeline-architecture) Pipeline Architecture -------------------------------------------------------------------------------------------------------------------- spinner [](https://docs.nfh.global/finternet/architecture/event-processing#why-async) Why Async? --------------------------------------------------------------------------------------------- Token operations involve multiple steps β€” pre-hook validation, state changes, commitment computation, post-hook execution. Processing them synchronously would: * Block the API thread during computation-heavy operations (commitment hashing) * Couple API availability to Token Engine availability * Make it harder to implement retry logic and idempotency The async model decouples the request acceptance (API) from the execution (Token Engine), providing better throughput, resilience, and operational flexibility. [](https://docs.nfh.global/finternet/architecture/event-processing#event-flow) Event Flow ---------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/finternet/architecture/event-processing#id-1.-api-publishes-event) 1\. API Publishes Event When a token operation is requested, the API validates the request (auth, RBAC, basic validation) and publishes an event to Kafka: GitBook AssistantAskCopy { "event_id": "uuid", "operation": "transfer", "token_id": "uuid", "payload": { ... }, "metadata": { "transaction_id": "uuid", "timestamp": "2026-04-06T12:00:00Z", "caller_id": "uuid" } } The API returns a `transaction_id` with status `submitted` to the caller. ### [](https://docs.nfh.global/finternet/architecture/event-processing#id-2.-token-engine-consumes) 2\. Token Engine Consumes The Token Engine (Rust) consumes events from the Kafka topic: 1. **Deserialise** the event 2. **Load** the token state from PostgreSQL 3. **Route** to the appropriate token program based on the token class 4. **Run pre-hooks** β€” validate the operation against configured rules 5. **Execute** the state change (atomic database transaction) 6. **Compute commitment** β€” SHA-256 hash of the new state 7. **Run post-hooks** β€” trigger side effects (webhooks, notifications) 8. **Update** the transaction status to `successful` ### [](https://docs.nfh.global/finternet/architecture/event-processing#id-3.-error-handling) 3\. Error Handling If processing fails: * **Transient errors** (database timeout, network issue) β€” retry with exponential backoff * **Permanent errors** (validation failure, insufficient balance) β€” mark as `failed` immediately * **Exhausted retries** β€” move to the Dead Letter Queue (DLQ) for manual investigation [](https://docs.nfh.global/finternet/architecture/event-processing#processing-guarantees) Processing Guarantees -------------------------------------------------------------------------------------------------------------------- Guarantee Mechanism **At-least-once delivery** Kafka consumer commits offset after successful processing **Idempotency** Transaction ID deduplication β€” reprocessing the same event produces the same result **Ordering** Events for the same token are processed in order (partition by token ID) **Atomicity** State change + commitment update in a single database transaction [](https://docs.nfh.global/finternet/architecture/event-processing#monitoring) Monitoring ---------------------------------------------------------------------------------------------- The Token Engine exposes metrics: * **Processing latency** β€” time from event consumption to completion * **Queue depth** β€” number of pending events * **Error rate** β€” failed operations per minute * **DLQ depth** β€” events that exhausted retries * **Hook execution time** β€” latency per hook All metrics are exported via OpenTelemetry to HyperDX for observability. [PreviousData Model](https://docs.nfh.global/finternet/architecture/data-model) [NextSecurity Model](https://docs.nfh.global/finternet/architecture/security-model) Last updated 1 month ago Was this helpful? * [Pipeline Architecture](https://docs.nfh.global/finternet/architecture/event-processing#pipeline-architecture) * [Why Async?](https://docs.nfh.global/finternet/architecture/event-processing#why-async) * [Event Flow](https://docs.nfh.global/finternet/architecture/event-processing#event-flow) * [1\. API Publishes Event](https://docs.nfh.global/finternet/architecture/event-processing#id-1.-api-publishes-event) * [2\. Token Engine Consumes](https://docs.nfh.global/finternet/architecture/event-processing#id-2.-token-engine-consumes) * [3\. Error Handling](https://docs.nfh.global/finternet/architecture/event-processing#id-3.-error-handling) * [Processing Guarantees](https://docs.nfh.global/finternet/architecture/event-processing#processing-guarantees) * [Monitoring](https://docs.nfh.global/finternet/architecture/event-processing#monitoring) Was this helpful? --- # Manage Supply | Finternet | NFH Fabric The examples below call the hosted UNITS API via `$UNITS_BASE_URL` and `$UNITS_DEVELOPER_TOKEN`. Export these once as shown in [Environment Setup](https://docs.nfh.global/finternet/building/environment-setup) before running any snippet. After minting, you can manage the lifecycle of your tokens: burn to reduce supply, freeze to suspend operations, lock to hold tokens as collateral, and update metadata. [](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#burn) Burn -------------------------------------------------------------------------------------- Destroy a token, permanently removing it from circulation. GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/burn \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.burn", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_id": "TOKEN_ID", "amount": 500 } }' [](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#freeze) Freeze ------------------------------------------------------------------------------------------ Suspend a token β€” the holder can still see it, but cannot transfer, burn, or modify it until unfrozen. Freeze is typically used for regulatory holds, dispute resolution, or compliance investigations. [](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#lock) Lock -------------------------------------------------------------------------------------- Place a hold on a token β€” it remains visible and the owner retains it, but it cannot be transferred. This is used for collateral, pledges, or escrow scenarios. [](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#update-metadata) Update Metadata ------------------------------------------------------------------------------------------------------------ Modify a token's metadata (within the constraints of the token class schema): [](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#claims) Claims ------------------------------------------------------------------------------------------ Attach or remove claims on tokens β€” references to credentials, agreements, or other tokens. ### [](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#add-claim) Add Claim ### [](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#revoke-claim) Revoke Claim [](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#all-operations-are-asynchronous) All Operations Are Asynchronous -------------------------------------------------------------------------------------------------------------------------------------------- Every supply management operation follows the same async pattern: the API returns a `transaction_id`, the Token Engine processes the operation via Kafka, and you poll the transaction status endpoint for the result. [PreviousProxy Tokens](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens) [NextCustom Token Programs](https://docs.nfh.global/finternet/token-manager-guide/custom-programs) Last updated 1 month ago Was this helpful? * [Burn](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#burn) * [Freeze](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#freeze) * [Lock](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#lock) * [Update Metadata](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#update-metadata) * [Claims](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#claims) * [Add Claim](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#add-claim) * [Revoke Claim](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#revoke-claim) * [All Operations Are Asynchronous](https://docs.nfh.global/finternet/token-manager-guide/manage-supply#all-operations-are-asynchronous) Was this helpful? GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/freeze \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.freeze", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_id": "TOKEN_ID" } }' GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/lock \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.lock", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_id": "TOKEN_ID", "lock_reason": "collateral_for_loan_xyz" } }' GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/update \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.update", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_id": "TOKEN_ID", "metadata": { "status": "redeemed", "redeemed_at": "2026-04-06T12:00:00Z" } } }' GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/claim/add \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.claim.add", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_id": "TOKEN_ID", "claim_type": "kyc_credential", "claim_reference": "CREDENTIAL_TOKEN_ID" } }' GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/claim/revoke \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.claim.revoke", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_id": "TOKEN_ID", "claim_id": "CLAIM_ID" } }' --- # Proxy Tokens | Finternet | NFH Fabric The examples below call the hosted UNITS API via `$UNITS_BASE_URL` and `$UNITS_DEVELOPER_TOKEN`. Export these once as shown in [Environment Setup](https://docs.nfh.global/finternet/building/environment-setup) before running any snippet. Proxy tokens let you bring **existing external assets** into the Finternet unified view without migrating them. The system of record stays where it is β€” public blockchain, private ledger, or institutional database β€” and UNITS maintains a read-shadow on top. [](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#when-to-use-proxy-mode) When to Use Proxy Mode ------------------------------------------------------------------------------------------------------------------------- A proxy token represents _any_ asset whose authoritative state lives outside UNITS. The external system can be: * A **public blockchain** β€” ERC-20 or ERC-721 on EVM chains, SPL tokens on Solana, UTXO-based assets, etc. * A **private or permissioned ledger** β€” CBDC pilot networks, settlement systems, consortium chains * An **institutional system of record** β€” core banking ledgers, custodian databases, KYC providers, or any internal API-addressable system Use proxy mode when: * You want users to see these external holdings alongside their native Finternet tokens * You want to apply Finternet policy rules (delegation, compliance) on top of external assets * You don't want to (or can't) migrate the authoritative record into UNITS [](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#how-it-works) How It Works ----------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#id-1.-register-the-external-token-class) 1\. Register the External Token Class Register the token class as a proxy, specifying the adapter and external contract: GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/class/register \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.class.register", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "name": "USDC (Ethereum)", "symbol": "USDC", "program": "fungible-token", "mode": "proxy", "adapter_config": { "adapter": "alchemy-evm", "chain": "ethereum-mainnet", "contract_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }, "metadata": { "description": "USDC stablecoin proxied from Ethereum" } } }' ### [](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#id-2.-register-existing-holdings) 2\. Register Existing Holdings For each user who holds the external token, register their holding as a proxy token in UNITS: ### [](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#id-3.-state-sync) 3\. State Sync The adapter queries the external system to keep the UNITS shadow state current. The adapter orchestrator routes requests based on priority and handles failover across configured providers. [](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#adapters) Adapters --------------------------------------------------------------------------------------------- Adapter Supported Systems Features **Alchemy EVM** Ethereum, Polygon, Arbitrum, Base, etc. Balance queries, transaction submission, event monitoring **Solana** Solana mainnet/devnet SPL token queries, transaction assembly and signing **Private Ledger** Custom (core banking, custodian APIs, internal systems) Authenticated API calls (mTLS, JWT, HMAC) Adapters are registered in the UNITS registry with system configuration, endpoint details, and priority settings. The adapter orchestrator provides automatic failover. [](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#transfers-for-proxy-tokens) Transfers for Proxy Tokens --------------------------------------------------------------------------------------------------------------------------------- When a user initiates a transfer of a proxy token: 1. UNITS pre-hooks validate the operation (delegation, compliance) 2. The adapter submits the transaction to the external system 3. After external confirmation, UNITS updates the shadow state 4. The transaction status is updated to `successful` The key difference from native transfers: the state change happens in the external system first, and UNITS updates its shadow after confirmation. [](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#limitations) Limitations --------------------------------------------------------------------------------------------------- * Proxy state may lag behind the external system depending on sync frequency * Commitment proofs rely on the external system's finality / authority model, not UNITS's per-token commitments * Policy enforcement is best-effort β€” if a user transacts directly in the external system (bypassing UNITS), the proxy state becomes stale until the next sync [PreviousMint Tokens](https://docs.nfh.global/finternet/token-manager-guide/mint-tokens) [NextManage Supply](https://docs.nfh.global/finternet/token-manager-guide/manage-supply) Last updated 1 month ago Was this helpful? * [When to Use Proxy Mode](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#when-to-use-proxy-mode) * [How It Works](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#how-it-works) * [1\. Register the External Token Class](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#id-1.-register-the-external-token-class) * [2\. Register Existing Holdings](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#id-2.-register-existing-holdings) * [3\. State Sync](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#id-3.-state-sync) * [Adapters](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#adapters) * [Transfers for Proxy Tokens](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#transfers-for-proxy-tokens) * [Limitations](https://docs.nfh.global/finternet/token-manager-guide/proxy-tokens#limitations) Was this helpful? GitBook AssistantAskCopy curl -X POST $UNITS_BASE_URL/v1/tokens/mint \ -H "Content-Type: application/json" \ -d '{ "context": { "id": "api.token.mint", "version": "1.0", "ts": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "msg_id": "'$(uuidgen)'", "developer_token": "YOUR_DEVELOPER_TOKEN" }, "payload": { "token_class_id": "PROXY_CLASS_ID", "owner_address": "USER_FINTERNET_ADDRESS", "amount": 1000, "metadata": { "external_address": "0xUserEthereumAddress", "external_chain": "ethereum-mainnet" } } }' --- # Security Model | Finternet | NFH Fabric Finternet follows a zero-trust security architecture. Trust is established through cryptography, not intermediaries. This page covers the key security mechanisms. [](https://docs.nfh.global/finternet/architecture/security-model#principles) Principles -------------------------------------------------------------------------------------------- 1. **Private keys never leave the user's device** β€” MPC key generation and signing ensure no single party holds the complete key. 2. **Fail closed** β€” Any authentication or authorisation error denies access. OPA evaluation errors return deny. 3. **Least privilege** β€” API clients receive only the scopes they need. Delegations grant only the permissions specified. 4. **Defence in depth** β€” Multiple layers of validation: API key β†’ client scope β†’ RBAC policy β†’ token program validator β†’ pre-hooks. [](https://docs.nfh.global/finternet/architecture/security-model#authentication-layers) Authentication Layers ------------------------------------------------------------------------------------------------------------------ ### [](https://docs.nfh.global/finternet/architecture/security-model#api-key-validation) API Key Validation 1. Extract developer token from request (body or header) 2. SHA-256 hash the token 3. Single indexed JOIN query: `api_keys INNER JOIN api_clients` on `key_hash` 4. Verify: key exists, not expired, not revoked, client active 5. Return 401 on invalid, 503 on database error (fail closed) ### [](https://docs.nfh.global/finternet/architecture/security-model#jwt-validation) JWT Validation For user-context operations: 1. Validate JWT signature against Keycloak's public key 2. Check expiration and issuer claims 3. Extract `account_id` and `preferred_username` (hashed address) ### [](https://docs.nfh.global/finternet/architecture/security-model#jws-verification) JWS Verification For high-risk operations: 1. Verify the JWS signature against the user's registered public key 2. Confirm the signed payload matches the request payload 3. This provides non-repudiation β€” cryptographic proof the user authorised the action [](https://docs.nfh.global/finternet/architecture/security-model#key-management) Key Management ---------------------------------------------------------------------------------------------------- ### [](https://docs.nfh.global/finternet/architecture/security-model#mpc-multi-party-computation) MPC (Multi-Party Computation) Finternet uses [Silence Laboratories](https://silencelaboratories.com/) for MPC key generation: * **Split-key generation** β€” The private key is generated in shares across multiple parties. No single party ever holds the complete key. * **Threshold signing** β€” A configurable subset of parties must cooperate to produce a valid signature. * **Supported curves** β€” secp256k1 (EVM) and ed25519 (Solana). * **WebAuthn binding** β€” MPC key shares are bound to device passkeys for biometric authentication. ### [](https://docs.nfh.global/finternet/architecture/security-model#hashicorp-vault) HashiCorp Vault Vault provides: * **PII encryption** β€” Email, phone, and other personally identifiable information is encrypted via Vault's transit engine before storage. The database never holds plaintext PII. * **Key material storage** β€” MPC key metadata and wallet references are stored in Vault. * **Entity management** β€” Each Finternet account is linked to a Vault entity for consistent encryption/decryption. [](https://docs.nfh.global/finternet/architecture/security-model#data-protection) Data Protection ------------------------------------------------------------------------------------------------------ ### [](https://docs.nfh.global/finternet/architecture/security-model#at-rest) At Rest * **PII** β€” Encrypted via Vault transit engine (AES-GCM-256). Database stores ciphertext. * **API keys** β€” Only SHA-256 hashes are stored. Plaintext shown once at creation. * **Passwords** β€” Not used. Authentication is via passkeys, OTP, or Keycloak SSO. * **Token state** β€” Stored in PostgreSQL with commitment hashes for tamper detection. ### [](https://docs.nfh.global/finternet/architecture/security-model#in-transit) In Transit * **HTTPS** β€” All API communication over TLS. * **Kafka** β€” Configured for TLS and authentication in production. * **Internal services** β€” Communicate over TLS within the Kubernetes cluster. [](https://docs.nfh.global/finternet/architecture/security-model#rbac-and-access-control) RBAC and Access Control ---------------------------------------------------------------------------------------------------------------------- See [Delegation and RBAC](https://docs.nfh.global/finternet/concepts/delegation-and-rbac) for the full access control model. Key security properties: * **OPA policies compiled at startup** β€” Not interpreted at runtime, reducing attack surface. * **Deny rules always win** β€” Explicit deny overrides any allow delegation. * **5-second delegation cache TTL** β€” Balances performance with revocation latency. * **Immediate key revocation** β€” Revoking an API key takes effect on the next request (no cache for key validation). * **Rate limiting** β€” Per-client, per-scope, configurable per tier. [](https://docs.nfh.global/finternet/architecture/security-model#audit-and-observability) Audit and Observability ---------------------------------------------------------------------------------------------------------------------- * **OpenTelemetry** β€” Distributed tracing across all services. * **Structured logging** β€” JSON-formatted logs with correlation IDs. * **Commitment proofs** β€” Every token state change is cryptographically committed. * **Delegation audit events** β€” Every delegation lifecycle change is recorded. * **HyperDX** β€” Centralised observability backend. [PreviousEvent Processing](https://docs.nfh.global/finternet/architecture/event-processing) [NextToken Program Interface](https://docs.nfh.global/finternet/reference/token-program-interface) Last updated 1 month ago Was this helpful? * [Principles](https://docs.nfh.global/finternet/architecture/security-model#principles) * [Authentication Layers](https://docs.nfh.global/finternet/architecture/security-model#authentication-layers) * [API Key Validation](https://docs.nfh.global/finternet/architecture/security-model#api-key-validation) * [JWT Validation](https://docs.nfh.global/finternet/architecture/security-model#jwt-validation) * [JWS Verification](https://docs.nfh.global/finternet/architecture/security-model#jws-verification) * [Key Management](https://docs.nfh.global/finternet/architecture/security-model#key-management) * [MPC (Multi-Party Computation)](https://docs.nfh.global/finternet/architecture/security-model#mpc-multi-party-computation) * [HashiCorp Vault](https://docs.nfh.global/finternet/architecture/security-model#hashicorp-vault) * [Data Protection](https://docs.nfh.global/finternet/architecture/security-model#data-protection) * [At Rest](https://docs.nfh.global/finternet/architecture/security-model#at-rest) * [In Transit](https://docs.nfh.global/finternet/architecture/security-model#in-transit) * [RBAC and Access Control](https://docs.nfh.global/finternet/architecture/security-model#rbac-and-access-control) * [Audit and Observability](https://docs.nfh.global/finternet/architecture/security-model#audit-and-observability) Was this helpful? --- # Architecture | Finternet | NFH Fabric This section is for builders who want to understand the internals of the UNITS system β€” how the components fit together, how data flows, and how to deploy and operate the stack. * [**System Components**](https://docs.nfh.global/finternet/architecture/system-components) β€” The services, languages, and how they interact * [**Data Model**](https://docs.nfh.global/finternet/architecture/data-model) β€” Database schema, JSONB patterns, and transaction lifecycle * [**Event Processing**](https://docs.nfh.global/finternet/architecture/event-processing) β€” Kafka pipeline, async operations, retries, and DLQ * [**Security Model**](https://docs.nfh.global/finternet/architecture/security-model) β€” Zero-trust, MPC keys, Vault, encryption [PreviousProgrammable Payments](https://docs.nfh.global/finternet/use-cases/programmable-payments) [NextSystem Components](https://docs.nfh.global/finternet/architecture/system-components) Last updated 2 months ago Was this helpful? Was this helpful? ---