Skip to main content
A Directory is the network’s public identity lookup service. Your client can use it to answer questions such as “Which encryption key belongs to this recipient?”, “Where can I deliver a message?”, and “Is this device still active?” Read-only requests are ordinary HTTP requests. Updates require a signature from a key already authorized by the DID.
Directory mutations use proof from the DID’s root key or another authorized DID key. Account-owner pallet calls remain available to developers who interact with the chain directly, but they are not exposed as Directory HTTP routes.
This reference documents only the public API contract. It excludes operational, diagnostic, test-only, and mesh-management interfaces. It does not describe OpenPayload’s internal validation, persistence, signing, or chain-submission logic.

​
Base URL

Use the HTTPS URL provided by your OpenPayload Directory operator.
The hostname in this documentation is a placeholder. Replace it with your operator-provided hostname. The API playground is disabled so examples cannot send requests to the placeholder. Send JSON request bodies with the Content-Type: application/json header. URL-encode DIDs, aliases, and document component IDs when you place them in a path.

​
API groups

DIDs

Resolve, register, and update public DID records.

Aliases

Add, update, and remove public aliases.

Personas

Register, renew, transfer, and manage a unique DNS-backed organization or collective name.

DID documents

Manage verification methods, authentication, key agreements, services, and the root key.

Delivery policies

Publish and resolve optional DID or Persona routing rules.

Applications

Register an Application, authorize its control targets, and read its independent policy.

​
Start with a read-only request

You can resolve a DID without installing an SDK, creating an account, or holding a private key:
Replace the hostname with a Directory operator’s HTTPS URL and the sample DID with the identifier you need.

​
Read requests and update requests

Authorization guide

Learn what a nonce is and how a client signs an update without revealing its private key.

​
Submission behavior

Mutation endpoints return 202 Accepted after the Directory accepts a request for processing. This status does not confirm final settlement. Accepted submissions return a public receipt containing the affected DID or Persona, operation or extrinsic name, and transaction hash. Some DID endpoints also include a human-readable message.

​
Errors

Newer endpoints return JSON errors with error and message fields. A details object appears only when the server has safe public context to return.
Do not log private keys, signing material, or unredacted authorization payloads. Public keys, DIDs, aliases, Personas, policy documents, tags, and service endpoints may become publicly discoverable.

​
Policies are optional

A DID or Persona can exist without a delivery policy. POST /delivery-policies/resolve returns 200 with applied: false when no rule applies. Relays then use the recipient DID’s ordinary service entries. Infrastructure failures and inactive Personas are errors and must not be treated as policy-free delivery.

Delivery-policy resolution

Resolve the winning Persona or DID rule from finalized chain state.

​
Straight to the point