Versions, revocation, and transfers

Versions and history

Read the current entry with GET /v1/entries/{did}. Enumerate versions with GET /v1/entries/{did}/versions, then retrieve a specific version with the version route. Updates use PUT /v1/entries/{did} with a newly signed payload, a scoped update_entry capability, and Idempotency-Key.

Revocation uses the protected DELETE route. It is a lifecycle mutation; do not treat it as erasing immutable audit history. Consumers must inspect lifecycle status when choosing usable entries.

Transfer is an explicit agreement

1. The current authorized owner creates a signed, expiring offer through POST /v1/transfers/{did}/offers.
2. The recipient reads the offer, checks its bound entry sequence and expiry, and explicitly accepts or declines it.
3. Acceptance validates the recipient and current state before ownership changes.

There is no supported unilateral /v1/transfer/{did} command. Offer, accept, and decline use distinct wire contracts and capabilities. Transfer API exposes each exact payload.

Race and retry handling

A concurrent update can invalidate a sequence-bound offer. Fetch current state and make a new deliberate offer instead of blindly retrying stale approval. Preserve idempotency keys for retries of the same operation.

Source authority

This page describes the checked-in implementation, not the availability of a public registry.

• mars-server/src/api/mod.rs
• mars-server/src/contracts.rs
• docs/api/openapi.v1.json
• mars-protocol/src/lifecycle.rs
• mars-protocol/src/api.rs