User Guide

Overview

The beckn.one Registry Service acts as the global directory of all platforms participating in the beckn.one network. It establishes addressability, allowing Beckn-enabled entities to:

  • Register their subscriber information

  • Make themselves discoverable

  • Authenticate and transact with other entities

  • Maintain verifiable public records under their own namespaces

Beckn one uses Dedi.global, an implementation of the Decentralized Directory protocol.

Once you register your subscription details on beckn.one, your network identity becomes publicly discoverable to all Beckn-compatible systems worldwide.

Adding Your Details to the Beckn.One Registry

Follow this guide to publish your subscriber details into the global directory.

Once you have completed the steps in the above guide you're ready to transact on Beckn.One!

✅ You are discoverable on beckn.one ✅ Your subscriber details are publicly resolvable ✅ Your Beckn ONIX installation can automatically fetch registry data ✅ You do NOT need to implement registry API services yourself

Beckn ONIX handles all interactions with the registry service, including:

  • Public key fetch via subscriber lookups

  • Signature validations during transactions

You should configure your beckn ONIX installation with <registry-url>/dedi as the registry URL and the record ID of the record you have created as the key ID.

Registry Service APIs - Technical Guide

The registry service is available in two environments:

  • Production: https://api.beckn.one/registry

  • Testnet: https://api.testnet.beckn.one/registry

All paths in this guide are relative to the chosen base URL.

Common Response Shape

All /dedi/* endpoints return JSON with this shape:

On error, the body is:

Please refer Error Handling section.

Endpoints

The following APIs are supported by the service:

  • Lookup APIs

    • Record Lookup

    • Registry Lookup

    • Namespace Lookup

  • Query APIs

    • Registry Query

    • Namespace Query

  • Search API

    • Record Search

Record Lookup API

GET /dedi/lookup/{subscriber_id}/{registry}/{record}

Retrieve a single record. The response also includes parent_namespaces field which is an array of namespaces that reference this record in their registries. This can be used to know which all facilitators within beckn.one have added this entity in their registries.

  • subscriber_id: subscriber_id of the entity. Also supports namespace ID of the record.

  • registry: registry name. Supports the wildcard registry subscribers.beckn.one to search across registries.

  • record: record ID.

Example:

Success response:

Registry Lookup API

GET /dedi/lookup/{namespace}/{registry}

Retrieve metadata about a registry.

  • namespace: namespace identifier. Accepts namespace ID or verified domain associated with the namespace.

  • registry: registry name.

Example:

Success response:

Namespace Lookup API

GET /dedi/lookup/{namespace}

Retrieve metadata about a namespace.

  • namespace: namespace identifier. Accepts namespace ID or verified domain associated with the namespace.

Example:

Success response:

Registry Query API

GET /dedi/query/{namespace}/{registry}

List records within a registry. References are resolved by the service to avoid subsequent lookups.

  • namespace: namespace identifier. Accepts namespace ID or verified domain associated with the namespace.

  • registry: registry name.

Example:

Success response:

Namespace Query API

GET /dedi/query/{namespace}

List registries within a namespace.

  • namespace: namespace identifier. Accepts namespace ID or verified domain associated with the namespace.

Example:

Success response:

Record Search API

GET /dedi/search/{namespace}

Search records within a namespace. You can filter by one or more query parameters.

  • namespace: namespace identifier. Accepts namespace ID or verified domain associated with the namespace.

Optional query parameters:

  • registry – limit results to a specific registry.

  • record_name

  • record_id

  • subscriber_id – matches subscriber_id in the record.

  • domain – matches domain in the record.

  • type – matches type in the record.

  • countries – match any element of countries[] in the record.

  • url – matches url in the record.

Example:

Success response:

If no records match the filters, data is an empty array.

Error Handling

The service uses standard HTTP status codes for /dedi/* endpoints:

  • 404 Not Found – resource not found (record/registry/namespace or no matching search results).

  • 503 Service Unavailable – cache refresh in progress; retry the request after a short interval.

  • 500 Internal Server Error – unexpected server error.

Error bodies have the shape:

Need Help?

If you need any assistance with onboarding, registry creation, or technical integration on beckn.one, please raise a support ticket here. Our team will get back to you promptly.

PreviousBeckn RegistryNextProduct Note

Last updated