SealBox API Reference

1. Introduction

SealBox is a trusted-timestamping API. You send it the SHA-256 hash of some content; it returns a receipt — a short, signed token asserting that the hash was presented to SealBox at a particular instant. Because the receipt is signed with HMAC-SHA-256 over a canonical payload, anyone holding the receipt can confirm it is authentic and unaltered.

SealBox never sees your content — only its hash — so you can seal secrets without disclosing them.

2. Core concepts

Term	Meaning
Content hash	A SHA-256 digest of your data, computed by you, client-side.
Receipt	A compact signed token, e.g. CSA-7K3P9Q2M4A-8F4A2C1D9E7B, that binds your hash to a signed timestamp.
Seal	The act of submitting a hash and receiving a receipt.
Verification	Re-checking a receipt's signature and (optionally) its bound hash.
Scope	Where a receipt is valid — live for production, sandbox for test receipts.

3. Authentication

All write calls are authenticated with a secret API key sent as a bearer token:

Authorization: Bearer sk_live_…

Keys are shown once, at creation, on your dashboard. Treat them like passwords: store them in a secret manager or environment variable, never in source control. If a key leaks, rotate it from the dashboard — the old key stops working immediately.

POST /v1/verify does not require a key: verification is public by design, so a counterparty can check your receipt without a SealBox account.

4. POST /v1/stamp

Seals a document hash and returns a signed receipt.

Request

Field	Type	Required	Notes
document	string	one of	Raw text to hash server-side (.txt, ≤ 16 KB). Convenient for demos.
sha256	string	one of	A 64-char hex digest you computed yourself. Preferred — your content stays local.
scope	string	no	live (default) or sandbox.

curl -X POST //sealbox.icu/v1/stamp \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"document":"hello world"}'

Response 200 OK

{
  "receipt":   "CSA-7K3P9Q2M4A-8F4A2C1D9E7B",
  "sha256":    "b94d27b9934d3e08a52e52d7da7dabfa…",
  "scope":     "live",
  "sealed_at": "2025-01-08T12:34:56Z",
  "expires_at":"2026-01-08T12:34:56Z"
}

Store the receipt — it is the only value you need to prove and to verify later.

5. POST /v1/verify

Checks a receipt's signature and reports what it attests. No API key required.

Request

Field	Type	Required	Notes
receipt	string	yes	The token returned by /v1/stamp.
sha256	string	no	If supplied, the endpoint also confirms the receipt was issued for this exact hash.

curl -X POST //sealbox.icu/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"receipt":"CSA-7K3P9Q2M4A-8F4A2C1D9E7B"}'

Response 200 OK

{
  "valid":     true,
  "receipt":   "CSA-7K3P9Q2M4A-8F4A2C1D9E7B",
  "issuer":    "sealbox",
  "scope":     "live",
  "sealed_at": "2025-01-08T12:34:56Z",
  "expired":   false
}

A tampered, expired, or unknown receipt returns { "valid": false, "reason": "…" }.

6. Anatomy of a receipt

A receipt looks like CSA-7K3P9Q2M4A-8F4A2C1D9E7B and has three dash-separated parts:

Part	Example	Meaning
Prefix	CSA	The receipt class (SealBox customer-account seals).
Handle	7K3P9Q2M4A	A random lookup key (Crockford base32).
Signature fragment	8F4A2C1D9E7B	Bytes of the receipt's real HMAC-SHA-256 signature.

SealBox keeps the full signed payload server-side; the compact token is a pointer plus enough of the signature to be cryptographically self-checking. That is why receipts are ~30 characters instead of a 300-character blob, yet still tamper-evident. Verification re-derives the signature and refuses any token whose fragment doesn't match.

7. Errors

Errors use standard HTTP status codes and a JSON body { "error": { "code", "message" } }.

Status	Code	Meaning
400	invalid_request	Missing/oversized document, malformed sha256, or bad JSON.
401	unauthorized	Missing or invalid API key on a write call.
404	not_found	Unknown receipt on verify.
413	too_large	Document exceeds the 16 KB free-tier limit.
429	rate_limited	Daily/plan quota exceeded. Back off and retry later.

8. Rate limits & idempotency

The Hobby Seal (free) tier allows 5 seals per day and documents up to 16 KB. When you hit the limit you receive 429 rate_limited — respect it with exponential backoff rather than a tight retry loop.

Sealing is idempotent per content hash within a scope: submitting the same hash again returns the original receipt and timestamp rather than minting a duplicate. Each payload also carries an internal nonce so distinct seals never collide.

9. Quickstart

1. Create a free account (needs a GetVerified VET — see §10).
2. Copy your API key from the dashboard.
3. Seal something:

   SHA=$(printf 'hello world' | shasum -a 256 | cut -d' ' -f1)
   curl -s -X POST //sealbox.icu/v1/stamp \
     -H "Authorization: Bearer sk_live_…" \
     -d "{\"sha256\":\"$SHA\"}"

4. Save the receipt. Verify it anytime, no key required:

   curl -s -X POST //sealbox.icu/v1/verify \
     -d '{"receipt":"CSA-…"}'

10. Getting an account

Creating a SealBox account requires a Verified-Email Token (VET) from GetVerified — this is how we confirm a real, reachable email is behind the account. The flow:

1. Get verified at GetVerified ↗, which issues you a VET.
2. Return to SealBox signup, fill in your details, and paste the VET.
3. Your Hobby Seal account and API key are created instantly.

The signup form accepts both individuals and companies; company name and billing address are optional on the free tier.

11. Sandbox

The sandbox lets you obtain a signed CS-ACCOUNT receipt without an API key — after passing a short in-house Developer Enrollment quiz on responsible API usage. Sandbox receipts carry scope: sandbox so they can never be confused with live seals.

12. Accepted verification alternatives

Account creation normally needs a VET. If you don't have one yet, either of these gets you there:

• Developer sandbox — pass the Developer Enrollment quiz and the sandbox issues a signed CS-ACCOUNT that Identifly recognizes.
• Support courtesy token — GetVerified's clerk can issue a one-off courtesy VET once you can show a genuine attempt is on file.

13. FAQ

Do you store my document? No. Prefer the sha256 field and your content never leaves your machine. The document field is a convenience for demos only.

Can I verify offline? Yes — the receipt's signature fragment is checkable against the public verification rules; the /v1/verify endpoint is a convenience, not a requirement.

What happens when a receipt expires? Verification still confirms the signature but reports expired: true. Re-seal to obtain a fresh receipt.

Is this legally binding? No. It's a demonstration service. See Terms.