Skip to main content
The current alpha uses /policies/v4 for signed policy document publication. The supported document format is openpayload-policy, version 1. This page retains its existing documentation URL; the HTTP routes below are the current contract. Legacy V3 typed-policy writes are retired. scope is did, persona, or application. URL-encode the complete id. The owner is the active DID, the Persona’s operator DID, or the Application’s current control DID. Network identities must use did:openpayload:<Base58Address>. Private keys remain in your client.

Prepare the request

Use POST /policies/v4/{scope}/{id}/prepare with: The Directory validates supported document semantics, service targets, and Call authority. It fills the current owner nonce and next revision, defaults expiry to five minutes, and returns scope, operator_did, canonical_payload, and request. Preparation neither publishes a policy nor verifies a signature. For this example, example.com must already be an active DNSSEC Persona owned by your DID. Replace the sample signing-key ID with an authorized key and the URL with your receiver under that domain. Save the draft as policy-draft.json.
Replace the Directory origin before running:
The returned request includes document_hex, content_hash, genesis_hash, revision, nonce, valid_until, and canonical_payload, plus your action and signer. document_hex is the exact document byte sequence; content_hash is its Blake2-256 hash. Review those bytes and the intended operation before signing. Readable document, when retained, must match the exact bytes.

Sign and submit

Decode the hexadecimal canonical_payload and sign those exact binary bytes locally with the authorized Ed25519 key. Add a Base64 or hexadecimal signature to the returned request, preserve all other fields, and save it as policy-request.json.
Do not sign the printed hexadecimal characters or JSON request text. Do not reserialize the document after signing. Signed submission requires exact document_hex; changing whitespace in those document bytes changes their integrity hash and authorization. The proof binds the chain genesis, owner DID, signing-key ID, operation, scope, next revision, exact document bytes, owner nonce, and expiry. Your client needs no SCALE implementation or funded transaction account when using Directory preparation. Choose a trusted Directory and verify its TLS connection. 202 Accepted means accepted for processing. Read finalized state until the intended revision and content hash appear. The first document revision is 1, independently of any frozen legacy revision; replacements and clears advance it. Another document-policy operation from the same owner can consume the nonce first. If the nonce, owner, or revision changes, prepare and sign again.

Read the record

GET /policies/v4/{scope}/{id} returns scope, policy_document, block_hash, and block_number. The record contains scope, revision, operator_did, content_hash, document_hex, cleared, and its finalized block context. Application scopes also include application_id, control_did, and application_revision. Decode document_hex to read the published document. Check its content hash, format, and version before interpreting it. A readable raw record is not permission to execute its actions. Direct chain publication can contain unsupported bytes; the Directory can expose those bytes with validation_error, and services must reject them for execution. Policy reads can also fail when current owner or domain authority is invalid. Call-bearing documents include validated call_domain and Unix-millisecond call_domain_expires_at metadata when applicable. A 404 policy_document_not_found means no document-generation record exists. A compatible resolver may then consider frozen legacy policy reads; it does not prove that the scope has no policy of any generation.

Clear a policy

Prepare using the same endpoint:
Omit both document and document_hex. Decode and sign the returned canonical_payload, add signature to the returned request, and submit that complete object as the JSON body of DELETE /policies/v4/{scope}/{id}. After 202, confirm the new finalized revision and cleared: true. A clear retains an empty document record; it does not return the scope to a missing-record state. It can also create revision 1 for a never-written document scope, suppressing frozen legacy policies. Normal Persona-to-DID selection remains available where applicable.

Compatibility and resolution

Use POST /delivery-policies/v4/resolve to resolve current recipient routing from one finalized snapshot. A document record takes precedence over frozen typed policies for the same scope. Unsupported or invalid documents fail rather than falling back to older rules. A cleared record masks older policies for that scope. Legacy V3 reads return 409 policy_document_reader_required when a document record exists. Legacy typed writes return 409 policy_document_writer_required. Use shared policies and control actions for document semantics, domain permissions, and receiver checks.

Errors

Other malformed, missing, inactive, expired, or unauthorized scopes are also rejected. A lookup or authorization failure must never be treated as permission to execute cached actions.

Straight to the point

  1. Prepare a set_policy_document or clear_policy_document draft through /policies/v4.
  2. Review the exact returned document and operation, then sign the decoded canonical_payload locally.
  3. Submit the returned request with signature using PUT or DELETE.
  4. Confirm the finalized revision, hash, and cleared state before relying on the result.