API reference

Everything in the dashboard, as an API.

Create receipts for anything, send end-to-end encrypted agreements, prove facts in zero knowledge, issue Proof Cards, seal documents until a deadline or an approval, collect anonymous verified responses, and verify all of it. Attest handles the wallets, the gas, and the blockchains behind every call. You send JSON. What only a person's passkey can do is listed under Kept with the person.

Authentication

Create an API key in the dashboard (Build, then Developers, then New key) and send it as a bearer token. A key acts as the account that created it. Verification endpoints, and the others marked Public, need no key. To try any endpoint with your key before writing code, open the API playground.

Authorization: Bearer ak_live_...

Errors and limits

Errors use HTTP status codes and a consistent body. On the free plan, 2 documents sent for signature, in total; for the other tools, 10 records a month: receipts, compliance proofs, Proof Cards, and certificates you create, and sealed calls, releases, vaults, and forms. Each agreement a free account creates counts against both: it uses one of the 2 documents and one of that month's records. Creating a receipt, agreement, compliance proof, or Proof Card returns your allowance in X-Attest-Quota-* headers. Signing, agreement proofs (Share proof), reading, and verifying never count. Each API key can make up to 300 requests a minute; past that, requests get 429 rate_limited with a Retry-After header. Requests with an invalid key count too.

{ "error": { "code": "quota_exceeded", "message": "Free plan limit of 10 records this month reached." } }

Pay per record (x402)

When your allowance is used up, an AI agent or script can pay for one more record in the request itself, with x402: no card, no plan change. Creating a receipt, compliance proof, Proof Card or certificate then answers 402 quota_exceeded with a PAYMENT-REQUIRED header: US$0.01 in USDC on Base, paid to Attest. Sign the payment with any x402 client and send the same request again with a PAYMENT-SIGNATURE header (or X-PAYMENT, x402 v1). Coinbase's x402 facilitator verifies and settles it, the record is created, and the response carries the settlement in PAYMENT-RESPONSE.

Your API key is still required: a payment buys a record for your account, never an anonymous one. Each settled payment adds one credit, once; if the request fails after the payment settles, the credit stays on your account for the next record. A payment for less, or to another address, is refused with the 402 and the terms again.

Receipts

A receipt proves that content with a given SHA-256 fingerprint existed, unchanged, at a point in time. Hash locally and send only the fingerprint: your content never has to leave your systems. Receipts are batched and anchored on a public blockchain within minutes.

curl -X POST https://attest.datahubz.com/api/v1/receipts \
  -H "Authorization: Bearer ak_live_..." -H "Content-Type: application/json" \
  -d '{
    "kind": "agent_action",
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "claim": "Agent invoice-bot filed the Q3 VAT return",
    "metadata": { "agentId": "invoice-bot", "authorizedBy": "cfo@acme.com" }
  }'

{ "id": "rcpt_01JD...", "kind": "agent_action", "status": "pending", "anchor": null, ... }

Verify (public)

Anyone can verify, with no account and no key, up to 300 requests per 10 minutes from one IP address. The same checks power the verifier at attest.datahubz.com/verify. New to Attest? Start with the introduction.

curl -X POST https://attest.datahubz.com/api/v1/verify -H "Content-Type: application/json" \
  -d '{ "sha256": "'"$(shasum -a 256 contract.pdf | cut -d' ' -f1)"'" }'

Agreements

Agreements are end-to-end encrypted: you encrypt the document before sending it, so Attest only ever stores it as ciphertext, and the document key you wrap to each party's key opens it, so only you and your signers can ever open an agreement created this way. (In the dashboard, a sender can instead choose Ready now for a signer new to Attest, which keeps a sealed copy of the document's key with our signing service until the signer first opens it, then deletes that copy.) Each party has their own key pair, set up once with a passkey: you set yours up in the dashboard, and each signer sets theirs up from the signing link they're emailed. When everyone has signed, the agreement is anchored on a public blockchain from its creator's wallet.

Encrypting a document

Generate a random 256-bit document key, encrypt the file with AES-GCM, and wrap the key to each party's RSA-OAEP (SHA-256) public key. Fetch public keys with POST /api/v1/keys/public, and check each one against the public key directory before wrapping anything to it (step 2 below): that check is what makes sure only the people you chose can open the document, even if Attest's servers were compromised. This runs anywhere WebCrypto does: Node 20+, Deno, Bun, or the browser.

import { readFile } from "node:fs/promises";
import { createHash, webcrypto as crypto } from "node:crypto";

const API = "https://attest.datahubz.com/api/v1";
const KEY = process.env.ATTEST_API_KEY;
const api = async (method, path, body) => {
  const res = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) throw new Error(JSON.stringify(await res.json()));
  return res.json();
};
const b64 = (buf) => Buffer.from(buf).toString("base64");

const me = "you@company.com";
const signers = ["mary@acme.com"];
const doc = await readFile("nda.pdf");

// 1. Public keys (yours is required; signers without one are granted later)
const { publicKeys } = await api("POST", "/keys/public", { emails: [me, ...signers] });

// 2. Check every key against the public key directory on Base before using it
const DIRECTORY = "0xb215B46EdEEc44Eab4FFf2e7565bB3aCB0aC92a6"; // AttestKeyDirectory, Base mainnet
const BASE_RPC = "https://mainnet.base.org";
const sha = (...parts) => createHash("sha256").update(Buffer.concat(parts)).digest();
const hex = (s) => Buffer.from(s, "hex");
const emailHash = (e) => createHash("sha256").update(e.trim().toLowerCase()).digest("hex");
const bitAt = (b, d) => (b[d >> 3] >> (7 - (d & 7))) & 1;
const empty = [Buffer.alloc(32)];
for (let h = 1; h <= 256; h++) empty.push(sha(Buffer.from([1]), empty[h - 1], empty[h - 1]));
const proofRoot = (key, value, { bitmap, siblings }) => {
  const k = hex(key), bm = hex(bitmap);
  let node = sha(Buffer.from([0]), k, hex(value)), s = siblings.length - 1;
  for (let d = 255; d >= 0; d--) {
    const sib = bitAt(bm, d) ? hex(siblings[s--]) : empty[255 - d];
    node = bitAt(k, d) ? sha(Buffer.from([1]), sib, node) : sha(Buffer.from([1]), node, sib);
  }
  return s === -1 ? node.toString("hex") : null;
};
const withKeys = [me, ...signers].filter((e) => publicKeys[e]);
const dir = await api("POST", "/keys/directory", { emailHashes: withKeys.map(emailHash) });
const onChain = await (await fetch(BASE_RPC, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [
    { to: DIRECTORY, data: "0xca2869a0" + dir.seq.toString(16).padStart(64, "0") }, "latest"] }),
})).json(); // rootAt(seq), read from Base, not from Attest
if (onChain.result?.slice(2, 66) !== dir.root) throw new Error("directory root isn't the one on Base");
for (const email of withKeys) {
  const r = dir.results.find((x) => x.emailHash === emailHash(email));
  const keyFp = createHash("sha256").update(publicKeys[email]).digest("hex");
  // A key set up moments ago: POST /keys/directory/refresh, then check again.
  if (r?.keyFp !== keyFp || proofRoot(r.emailHash, keyFp, r.proof) !== dir.root) {
    throw new Error(`${email}'s key isn't the published one: don't encrypt to it`);
  }
}

// 3. Encrypt the document with a fresh key
const dek = crypto.getRandomValues(new Uint8Array(32));
const iv = crypto.getRandomValues(new Uint8Array(12));
const aes = await crypto.subtle.importKey("raw", dek, "AES-GCM", false, ["encrypt"]);
const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, aes, doc);

// 4. Wrap the key to each party
const wrap = async (spki) => {
  const pub = await crypto.subtle.importKey("spki", Buffer.from(spki, "base64"),
    { name: "RSA-OAEP", hash: "SHA-256" }, false, ["encrypt"]);
  return b64(await crypto.subtle.encrypt({ name: "RSA-OAEP" }, pub, dek));
};
const signerWrappedDeks = {};
for (const email of signers) if (publicKeys[email]) signerWrappedDeks[email] = await wrap(publicKeys[email]);

// 5. Create it
const agreement = await api("POST", "/agreements", {
  title: "Mutual NDA, Acme & Co",
  documentName: "nda.pdf",
  documentSha256: createHash("sha256").update(doc).digest("hex"),
  document: { ciphertext: b64(ciphertext), iv: b64(iv), contentType: "application/pdf", size: doc.length },
  creatorWrappedDek: await wrap(publicKeys[me]),
  signerWrappedDeks,
  signers: signers.map((email) => ({ email })),
  includeSelf: true,
  sequential: true,
});

// 6. Email the signing links
await api("POST", `/agreements/${agreement.id}/send`);

Agreement actions

Zero-knowledge proofs

Prove a fact about a completed agreement you're a party to, revealing only that fact. Proofs are Groth16, checked against the anchored root of the agreement's tree (65,536 agreements each), and verified independently on zkVerify.

{ "id": "azk_01M3..." }

Compliance proofs

Compliance proofs run on the security-scan Groth16 circuit from Hubz VCE, a DataHubz project, in its second version: the proof reveals only whether the claim holds, bound to a salted commitment to the scan. Each proof is checked by Attest and verified on zkVerify, and its receipt is anchored on Base; the receipt's fingerprint is the hash of the commitment, so it reveals nothing about the scan either.

Proof Cards

Issue credentials people carry and prove anywhere: training, supplier approvals, memberships, employment, or your own fields. Each card is a W3C Verifiable Credential 2.0, signed by your organization with a Data Integrity proof (ecdsa-sd-2023), so the holder can reveal only the fields they choose and the signature still verifies. Revocation and suspension use W3C Bitstring Status Lists. Every issuance and every status-list change is anchored on Base, so an issuer can't backdate a card or hide a revocation. Issuing uses one record of your allowance; status changes, reading, and verifying don't.

Training cards are issued in the 1EdTech Open Badges 3.0 format (OpenBadgeCredential), so learning platforms and badge wallets can read them. You send the same fields; Attest maps completedOn to activityEndDate, hours to creditsEarned, result to a Result, and the title to the Achievement, which is always disclosed.

curl -X POST https://attest.datahubz.com/api/v1/credentials \
  -H "Authorization: Bearer ak_live_..." -H "Content-Type: application/json" \
  -d '{
    "template": "training",
    "title": "Forklift operator certification",
    "recipient": { "email": "mary@acme.com", "name": "Mary Ruiz" },
    "fields": { "completedOn": "2026-09-18", "hours": 16, "result": "Passed" }
  }'

{ "id": "cred_01M3...", "credentialId": "urn:uuid:...", "state": "active",
  "issuer": { "name": "Acme Training", "did": "did:web:attest.datahubz.com:orgs:acme-training" },
  "claimUrl": "https://attest.datahubz.com/cards/claim/...", "receiptId": "rcpt_01M3...", ... }

Checking a card without Attest. Everything a verifier needs is public and standard, so any software supporting these W3C specifications can check a card on its own:

Wallets: OpenID4VCI and OpenID4VP

Every card exists in two formats: an IETF SD-JWT VC (dc+sd-jwt, ES256, issuer did:web, revocation through an IETF Token Status List) following the FIDES DIIP v5 interoperability profile, and the W3C Verifiable Credential described above. Wallet apps pick the format they read.

Proof Cards work with wallet apps through the OpenID Foundation's standards. OpenID4VCI 1.0 delivers a card to a wallet: the holder clicks “Add to a wallet app” and gets a one-time QR code and a 6-digit PIN (pre-authorized code flow). A wallet that proves its key (a jwt proof, did:key or did:jwk) receives a copy bound to that key (cnf.kid for SD-JWT, credentialSubject.id for W3C); otherwise an unbound one. The authorization code flow is supported too, with pushed authorization requests and PKCE S256. OpenID4VP 1.0 lets you ask someone to present a card: wallet apps get a request object signed by Attest's did:web (passed by reference, request_uri_method=get), with a DCQL query accepting either format and direct_post. A presentation is accepted only with holder binding: an SD-JWT key binding JWT for this request, a W3C presentation signed by the key the card is bound to, or approval with the holder's passkey in Attest.

Check the card, not the screen. A wallet app's display, a screenshot, or a printout can't show that a card is still valid, and some wallet apps don't show a suspension or revocation to their user. Verify by requesting the card (below) or opening its share link: every check reads the issuer's status list at that moment. When an issuer suspends, reinstates, or revokes a card, Attest emails the holder.

{ "id": "vpr_01M3...", "status": "waiting",
  "walletLink": "openid4vp://?client_id=redirect_uri%3A...&dcql_query=...",
  "attestLink": "https://attest.datahubz.com/present?...", "expiresAt": "..." }

Certificates

An organization attests statements about a subject, as of a point in time: a security assessment passed, an audit completed, a standard met. Each person named as a signer reviews it and signs its exact content with their passkey; then the organization signs it as a W3C Verifiable Credential (vc+jwt, ES256, the key in its DID document), Attest renders the PDF, and both are anchored on Base from the organization's own wallet. Certificates are public: anyone can open https://attest.datahubz.com/certificates/{id}, run every check in their browser, or find it by dropping its PDF (or a document it lists) on the verifier.

Findings closure. For an assessment certificate, send the findings with findingsClosure. Attest proves in zero knowledge (Groth16, findings_closure.circom) that every finding in the set is closed, without revealing how many there were, what they were or their severities. The findings are committed as a salted Poseidon hash chain bound to this certificate; the commitment becomes part of the content every signer signs and is anchored with the certificate, and the proof is verified on zkVerify. A set with any open finding is refused, and the circuit itself can't prove one. The response's findingsClosure.salt is returned once and never stored: keep it with the findings, so an auditor can recompute the commitment:

context   = sha256("attest.certificate.findings|" + certificateId) mod p
id_i      = sha256("attest.finding|" + findingId) mod p       (chain in ascending id_i order)
acc_0     = Poseidon(context, n, salt)
acc_{i+1} = Poseidon(acc_i, id_i, severity_i, 1)              severity: info 0 … critical 4
commitment = acc_n                                            (p = the BN254 scalar field)

The certificate's page verifies the proof in the visitor's browser, against the published verification key, and shows zkVerify's verdict.

Sealed submissions

Collect proposals, bids, or applications that no one can open before a deadline. Each submission is encrypted in the submitter's browser with a fresh AES-256 key; that key is wrapped to every reviewer's public key, and the wrapped keys are time-locked with drand (quicknet, the League of Entropy) to the first round published at or after the deadline. Before then, no one can open a submission: the key that unlocks the time lock is produced by a threshold of independent drand operators only at that moment. After it, only the reviewers can, since Attest never holds their private keys. The call's terms (deadline, round, reviewers) are anchored when it's created, and every submission's sealed bytes when it arrives. Replacements are allowed before the deadline, and every version stays on record.

A key id, here and in the sections below, is the SHA-256 (hex) of the person's public key as its base64 SPKI text. Get public keys with POST /api/v1/keys/public (a sealed call lists its reviewers' keys with each one's emailHash), and check every key against the public key directory before wrapping anything to it, as the dashboard does.

Approval release

A document that opens for chosen recipients only after k of n approvers approve it, and optionally not before a date. It's encrypted in the creator's browser with a key K = K1 xor K2. K1 is split with Shamir's secret sharing into one share per approver (any k rebuild it; fewer reveal nothing), and each share is encrypted to that approver's public key. K2 is time-locked with drand to the “not before” date, or zero without one. Approving happens in the approver's browser: their share is decrypted with their key, re-encrypted to each recipient, and the decision is signed with their passkey. Recipients rebuild K from k shares (plus drand's key for the date). Attest only ever holds the document and its keys as ciphertext. The terms (approvers, threshold, recipients, date, document fingerprint) are anchored at creation, and every approval or decline when it's made.

Approving and declining are signed with the approver's passkey, so they happen in the dashboard.

Continuity vault

Documents and notes kept sealed until the moment others need them: handovers, account access, instructions. They're released to chosen beneficiaries only if the owner stops checking in and k of n trustees confirm. Each item is encrypted in the owner's browser with its own key; those keys are wrapped with a vault key V, which is wrapped to the owner and split among the trustees with Shamir's secret sharing. Once the owner misses a check-in plus the grace period, each trustee can confirm with their passkey, re-encrypting their share to the beneficiaries in their own browser. A check-in cancels outstanding confirmations, and locks a released vault again unless a beneficiary has already received it. Changing trustees or beneficiaries re-keys the vault. The terms, every item and every confirmation are anchored.

What's guaranteed by cryptography: fewer than k trustees can't open it, and neither can Attest. What's Attest's rule: the check-in timer, which decides when trustees may confirm.

Check-ins and trustee confirmations are signed with a passkey, so they happen in the dashboard.

Verified Forms

Anonymous responses from a known group, one per member: team pulses, committee votes, member and customer feedback. Built on Semaphore v4 (Groth16 on BN254). Each invited member joins by creating a per-form identity in their browser; only its commitment joins the group (a Merkle tree). A response carries a proof that its author is in the group, bound to the exact answers (the proof's message is sha256(canonicalJson({ form, answers }))) and to the form (its scope). The nullifier is the same for any two responses from one member, so a second response is refused, without revealing who either came from. Responses are submitted without a session. Every proof is verified by Attest and also on zkVerify.

The terms are anchored at creation; with “join first, then answer”, the group is fixed and anchored when answering opens; the full set of responses is anchored at close. Answering needs at least 3 members in the group. The evidence file contains everything needed to re-check the results: the group's commitments, and every response with its proof (depth 16).

Joining happens in the dashboard, where the member's identity is created. What's guaranteed by cryptography: a response can't be linked to a member from the data, by the organizer or anyone checking the evidence, and nobody can answer twice or without being on the list. What remains: Attest's servers see when requests arrive; we don't link a member's visit to a response, and written answers can reveal their author by what they say.

Integrations

Platforms that serve many organizations (a hotel system, a compliance platform) use the Integrations API instead of an account key: an integration key (ik_live_…) registers organizations, each with its own wallet, records events as one transaction each, and records daily state proofs verified on zkVerify. It has its own guide, with endpoints, webhooks and a TypeScript client: Integrations.

Kept with the person, by design

• Keys and passkeys. Your private key is created and unlocked in your browser with a passkey, and reaches our servers only encrypted, so we can't use it. Set it up once on the Security page. Your public key is listed in the public key directory; the Security page shows your key fingerprint, checks your own entry in every published root, and gives you safety numbers to compare with the people you share with.
• Opening documents. Decryption happens where your key is. Through the API you receive ciphertext and decrypt it yourself.
• Anything signed with a passkey. Signing an agreement (in the dashboard, from a signer's emailed link, or through your own WebAuthn integration, above), approving or declining a release, checking in on a vault, confirming as a trustee, and approving a Proof Card share are made by the person's passkey (Face ID, Touch ID, Windows Hello or the device PIN), so no API key alone can do them on anyone's behalf. Each is verifiable by anyone: POST /api/v1/verify with an agreementId returns every signer's evidence and our check of it.
• Holding cards. Accepting a Proof Card, sharing it, and adding it to a wallet app happen in the holder's dashboard.
• Joining a Verified Form. The member's identity for the form is created in their browser.
• Organizations, billing, and API keys. Managed in the dashboard.