File-based onboarding

Publish DeDi files on your own domain — publishing your index file and registry is your onboarding, for NFOs and NPs alike.

On this path you publish records directly on a domain under your own control, in conformance with the DeDi protocol specification.

Any file-based publisher — NFO or NP — must publish at least two files:

File	Location	Purpose	Schema
DeDi index file	https://<your-domain>/.well-known/dedi.index.json	Lists your signing keys and the registry files you publish	dedi-manifest.schema.json
Registry file(s)	URL declared in the index file (hosting conventions)	The registry records themselves, signed by you	dedi-file.schema.json; records follow beckn_subscriber_reference.json (NFO) or beckn_subscriber.json (NP)

Both files are signed with your key — see Signing your files below.

How a file-based network comes together

Publishing your DeDi index file and registry is your onboarding — for NFOs and NPs alike. The sequence below shows an NFO onboarding its network together with its NPs.

Step 1 — NFO expresses intent to join the NFH fabric. The NFO enters its domain on the NFH fabric onboarding portal.

Step 2 — NFO publishes its index and participant registry. The NFO publishes its DeDi index file at nfo.com/.well-known/dedi.index.json, and creates its reference registry of network participants — suggested name nfoname_networkname_env_ref_registry — at nfo.com/dedi/nfoname_networkname_env_ref_registry.json. The registry must use the Beckn Subscriber Reference schema.

Step 3 — NP publishes its records. The NP publishes its DeDi index file at np.com/.well-known/dedi.index.json, and creates its network key registry at np.com/dedi/nfoname_networkname_env_registry.json (e.g. nfo-x_mobility_prod_registry.json), using the Beckn Subscriber schema. It then shares its registry URL with the NFO.

Step 4 — NFO updates its records. The NFO adds the new NP's details to its registry of NPs, re-signs, and republishes.

In Steps 2–4, every file is signed before it is published — see Signing your files.

If you are an NFO

• Onboarding your network: do Steps 1 and 2 — express intent on the onboarding portal, then publish your index file and reference registry. See the NFO's index file and reference registry laid out in full in the worked example.
• Adding an NP to your network: do Step 4 each time an NP joins — add a record with the NP's subscriber_id and registry URL (in either URL form) to your reference registry, then re-sign and republish the registry file. If your index file carries a digest for that registry, also update the digest, then re-sign and republish the index file.

If you are an NP

Your onboarding is Step 3 — publishing your DeDi index file at np.com/.well-known/dedi.index.json and your network key registry at np.com/dedi/nfoname_networkname_env_registry.json, using the Beckn Subscriber schema. See NP1's index file and registry laid out in full in the worked example.

Each record in your registry describes one of your subscriber endpoints:

Field	What to fill	Example
Subscriber ID	Your unique identifier, typically your domain	np.com
Subscriber URL	Your ONIX receiver endpoint	https://np.com/beckn/bap/receiver
Type	Your role on the network	consumer node or provider node
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 a separate record for each role.

Your Subscriber ID must be your domain itself, or a subdomain of it — e.g. a domain of example.com may use subscriber IDs example.com or bap.example.com, but not something.com.

Generating the signing keypair for ONIX: you can use this utility script provided in ONIX, or any other tool, as long as it produces an Ed25519 key pair with the private key as the raw 32-byte seed and the public key as the raw 32-byte public key, both Base64-encoded (standard RFC 4648, with padding).

Sign your registry file with the key declared in your DeDi index file, then publish both.

• Joining under an NFO: share your registry URL with the NFO, which adds your record to its reference registry (Step 4).
• Not tied to any NFO yet: enter your domain on the NFH fabric onboarding portal yourself, then publish. You are then on the NFH fabric standalone, and NFOs can add you to their networks later.

Signing your files

dedi-cli generates your signing key, signs your index and registry files, and checks the signatures locally, as the DeDi protocol requires. Install it with Go:

go install github.com/nfh-trust-labs/dedi-cli/cmd/dedi-cli@latest

Or download a pre-built binary for Linux, macOS or Windows from the Releases page.

1. Generate a signing key (once):

dedi-cli keygen --kid key-1 --out key.json

key.json holds your private key. Keep it secret, never commit it, and back it up — you need it every time you re-sign.

This is not your ONIX key. You work with two different signing keys:

Key	What it signs	Where its public key goes
ONIX signing key	Beckn messages, live during transactions	signing_public_key in your registry record
DeDi file-signing key	Your index and registry files, when you publish	keys in your index file

We recommend a separate key for each. You can reuse one keypair for both (re-encoded for each place), but keeping them apart is safer: the ONIX key lives on a running server, while the DeDi key can stay offline. And if the ONIX key leaks or you rotate it, your index file isn't affected.

2. Sign each file. Fill in every field of the index or registry file except the signing key and proof, then:

dedi-cli sign --key key.json --in unsigned/nfo-x_mobility_prod_ref_registry.json --out signed/nfo-x_mobility_prod_ref_registry.json

sign detects whether the input is an index file or a registry file, adds your public key if it is missing, and writes the proof. Before signing, it also catches mistakes that would otherwise fail silently later:

• records whose details don't match the registry's schema;
• for Beckn Subscriber registries, a subscriber_id that is not your domain or a subdomain of it — DeDi never picks up such a record;
• a next_update that is already in the past.

If you're using a digest, sign the registry file first, then add its digest to the index file, then sign the index file.

3. Check the signature before you publish:

dedi-cli verify --in signed/nfo-x_mobility_prod_ref_registry.json

This only checks the signature itself, not domain binding or freshness. dedi-cli doesn't publish: upload the signed files to your domain yourself, exactly as sign wrote them.

Adding a digest (optional)

Each registry entry in your index file's files can carry a digest — a hash of the registry file's current content. The DeDi specification makes it optional, but it helps crawlers: a crawler compares the digest in your index file with the one it saw last time. If it hasn't changed, the crawler skips re-fetching the registry. If it has changed, the crawler fetches the new version. Without a digest, crawlers have to fetch the registry file itself to find out whether it changed.

The digest is the SHA-256 hash of the exact bytes of the signed registry file you publish, written as sha-256: followed by the lowercase hex hash:

macOS

echo "sha-256:$(shasum -a 256 signed/nfo-x_mobility_prod_ref_registry.json | cut -d ' ' -f 1)"

Linux

echo "sha-256:$(sha256sum signed/nfo-x_mobility_prod_ref_registry.json | cut -d ' ' -f 1)"

Windows (PowerShell)

"sha-256:" + (Get-FileHash signed\nfo-x_mobility_prod_ref_registry.json -Algorithm SHA256).Hash.ToLower()

Put the result in that registry's files[].digest in your index file, then sign the index file. Keep these rules in mind:

• Hash the signed file. Compute the digest after signing the registry, and publish that file unchanged — reformatting or re-saving it changes the bytes and breaks the digest.
• Update it on every change. Each time you re-sign a registry, recompute its digest, update the index file and re-sign it too. A stale digest makes verifiers reject the registry until the index file catches up.
• Or keep it in a separate digests file. To avoid re-signing your index file on every registry change, you can put digests in a signed digests file linked from the index file's digests URL instead — see §6.3 of the specification.

Reuse of an existing dedi.global presence

Where an NP already maintains a presence on dedi.global, that existing record may be used for onboarding, without requiring the NP to publish files independently. In this case, the lookup URL from dedi.global can be used in the NFO's registry, for example:

https://api.dedi.global/dedi/lookup/np2.com/nfo-x_mobility_prod_registry

Registry URL forms

An NP's registry URL can be in one of two forms, depending on the path the NP uses:

NP path	URL form	Example
Hosted	api.dedi.global/dedi/lookup/<domain>/<registry-name>	https://api.dedi.global/dedi/lookup/np.com/nfo-x_mobility_prod_registry
File-based	<domain>/dedi/<registry-name>	https://np.com/dedi/nfo-x_mobility_prod_registry

See all of these files fully written out in the worked example.