Revoke proof
Revoke a proof token, making it invalid. Accepts the public proof handle (ph_ctl_<32 hex> or ph_dlg_<32 hex>) or a verification id — the same addresses the status, suspend and unsuspend routes take. Revoking a PROOF does not withdraw the asset, consent or delegation it is about: those have their own surfaces. The revocation reaches the registry row, GET /proofs/{id}/status, POST /proofs/validate, the revocation list and the Token Status List. One difference between the two addresses: by verification id a proof whose verification is not verified answers not_verified, while by handle it is revoked anyway — the registry row is live and would otherwise keep validating — leaving the verification in whatever state it really ended in. Reachable with an API key (proofs:write) or a dashboard session cookie; the scope binds API-key callers only. A CONTROL proof — a domain proof delegations can hang off (ph_ctl_* of a domain asset or verification, or a domain verification id) — takes the gated path (h-implement-proper-deletion, DOM-3): for a domain the account OWNS the whole-domain cascade runs (every proof of the domain and every delegation issued from it revoked, the domain demoted to reverification_required with its DNS challenge rotated — the same act as DELETE /me/assets/{id} on the domain asset); for a bare verification of somebody else's domain only that proof and the delegations anchored on it are revoked, sibling verifications stay live. The body then carries principal, owned_domain, domain_status and delegations_revoked. A repeat answers 200 while something was left to re-drive (a delegation still live under a revoked proof), else 400 already_revoked — decided before any step-up code is spent. A handle revoked BEFORE the domain was proven again answers 400 already_revoked and never reaches the new proof: revoke that one by its own handle. An API key revoking a control proof, or one of the account's own phone or email proofs, has the act recorded for the hourly owner digest (one digest per key).
Request
- Base URL: https://api.proof.holdings
- URL: https://api.proof.holdings/api/v1/proofs/{id}/revoke
- Auth: one of:
- HTTP bearer
- API key in cookie auth_token
Path parameters
Public proof handle (ph_ctl_<32 hex> / ph_dlg_<32 hex>) or verification id
Request body
Example request
{
"reason": "user_request"
}Response
Proof revoked
Example response
{
"success": true,
"proof_id": "ph_ctl_0123456789abcdef0123456789abcdef",
"proof_type": "verification",
"verification_id": "507f1f77bcf86cd799439011",
"revoked_at": "2026-02-13T12:00:00Z",
"reason": "user_request",
"principal": "example.com",
"domain_status": "reverification_required",
"delegations_revoked": [
{
"proof_id": "ph_dlg_0123456789abcdef0123456789abcdef",
"delegate": "pkg:npm/@acme/cli",
"delegate_type": "purl",
"principal": "example.com"
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.