Proofs

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).

post/api/v1/proofs/{id}/revoke

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

idstring required

Public proof handle (ph_ctl_<32 hex> / ph_dlg_<32 hex>) or verification id

Example:ph_ctl_0123456789abcdef0123456789abcdef

Request body

reason'user_request' | 'fraud' | 'key_compromise' | 'asset_transferred' | 'other'

Reason for revoking a proof

Example request

{
  "reason": "user_request"
}

Response

Proof revoked

successboolean required
proof_idstring

Public proof handle (ph_ctl_*/ph_dlg_*). Present when the proof was addressed by handle.

proof_typestring

Which record carries the revoked proof (verification, user_asset, verification_request, delegation, …). Present when the proof was addressed by handle.

verification_idstring

Present only when the revoked proof belongs to a verification.

revoked_atstring date-time required
reasonstring required
principalstring nullable

Control proofs only: the domain the proof is about.

owned_domainboolean

Control proofs only: true when the account OWNS the domain (a Domain row or a domain asset for the name) and the whole-domain cascade ran — every proof of the domain and every delegation issued from it revoked, the domain demoted to reverification_required. False for a bare verification of somebody else's domain: that proof and the delegations anchored on it only.

domain_statusstring nullable

Control proofs only: the Domain row's status after the act (reverification_required after the cascade); null when the account has no Domain row for the name.

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.