Skip to main content

​
Verification

ProofRail verification has two current surfaces:
  • Tokenized public verification for sharing a minimized verification result outside your account
  • Authenticated v2 verification for organization members and admins inside your account
The older raw UUID public approval routes remain temporarily operational for compatibility, but new integrations should not construct raw UUID public links.

​
Preferred public verification

Public verification uses an opaque token:
The token is intentionally opaque. Treat it as a bearer secret for the public verification result it unlocks.
The plaintext public token is returned once, only in the creation response. After that response is gone, ProofRail stores only a token hash. Existing public links cannot be recovered from the API; revoke and issue a new token if the link is lost.
Public v2 responses are minimized for sharing. They report high-level artifact type, verification status, integrity status, signature status where applicable, key-trust status, and timestamp-anchor status. They do not expose raw signatures, HMACs, proof blobs, internal organization identifiers, actor details, policy payloads, or full snapshots.

​
Authenticated v2 verification

Authenticated callers should use the v2 verification routes:
Approval verification separates integrity, Ed25519 signature status, key trust, FreeTSA status, OpenTimestamps status, and overall result. Historical approval signing keys are reported with key_status: "not_evaluated" until the G1B key-registry work is complete. Receipt verification is server-attested integrity verification. It checks the server-generated receipt data and HMAC/hash-chain continuity through the backend. It is not an independent offline proof export. Member and admin responses differ. Members receive safe verification and artifact metadata. Admins may receive additional allowlisted audit context, such as reviewer attribution and sanitized review summaries, when their role permits it.

​
Admin token management

Admins manage public verification tokens through authenticated routes:
Issuing a token returns the plaintext token and suggested public path once. List and revoke responses never return plaintext tokens or token hashes. Use placeholder values in examples and logs:
Do not place real public tokens, receipt IDs, approval IDs, signatures, keys, or proof material in documentation, support tickets, screenshots, or logs.

​
Migration guidance

Stop constructing public links from raw approval UUIDs. Instead:
  1. An admin issues an opaque public verification token for the approval or receipt.
  2. The creation response returns the plaintext token once.
  3. Share the resulting /public/v2/verify/{opaque_token} link only with intended recipients.
  4. Revoke the token if access should end, or if the plaintext link is lost.
Existing legacy UUID approval links remain compatibility-only. They are still operational while first-party clients and customers migrate, but they should not be used for new integrations. SDK callers should use the v2 helpers:
The legacy SDK receipt helper remains temporarily callable for compatibility and emits a deprecation warning.

​
Current boundaries

  • Raw/offline evidence export is future work.
  • No hard Sunset date exists for legacy UUID routes.
  • Legacy route removal requires telemetry, customer notice, support exceptions, and later approval.
  • Approval key trust remains not_evaluated for historical keys until G1B.
  • External timestamp anchors report their own status and do not override local signature results.