Skip to main content
Read-only requests do not require your private key. Updates do, because a Directory must distinguish the DID controller from somebody merely claiming to be the controller. Authorization happens entirely on your device:
  1. Read the current nonce.
  2. Build the operation’s canonical payload.
  3. Sign the exact payload bytes with an authorized Ed25519 key.
  4. Send the public fields, encoded payload, and signature.
The Directory receives no private key.

​
Nonces prevent replay

A nonce is a counter associated with a DID authorization domain. Once a nonce is used successfully, another request cannot safely reuse it. Fetch current values with:
Use the nonce named for the operation you are building. If another update is submitted first, fetch the values again and rebuild the signature.

​
Expiration limits stolen requests

valid_until is an unsigned 64-bit Unix timestamp in milliseconds for SCALE authorization payloads. Use a short future window and make sure the machine signing the request has an accurate clock.

​
Canonical payloads are bytes

For DID-document component operations, canonical_payload is the exact SCALE-encoded authorization structure. Send it as:
  • Hex beginning with 0x, or
  • Standard or URL-safe Base64
The Directory decodes the value, reconstructs the expected structure from the other request fields, and compares the bytes. Signing a JSON object or a visually similar string will not work. The document authorization field order is: Each endpoint page identifies which optional item is populated.
Alias authorization is temporarily unavailable as a stable cross-client contract while its runtime SCALE payload is synchronized. Do not build production alias mutation signing from the current JSON placeholder.

​
Sign the bytes, not their printed encoding

If canonical_payload is Base64, decode it and sign the decoded bytes. Do not sign the Base64 characters. The resulting Ed25519 signature is sent as Base64 in signature.

​
Signer selection

Set signer_key_id to:
  • root to use the record’s root public key, or
  • A complete authorized verification-method ID such as did:talaria:...#signing
The key must already be authorized by the DID record.

​
Why the body repeats the DID and action

The path selects the resource. The signed body binds the authorization to the same DID and one exact operation. The Directory rejects a mismatch rather than guessing what the caller intended.

​
Straight to the point

Never send private_key, a mnemonic, or a seed phrase.