Start writing

Checking a certificate from code

Last updated 15 October 2026

Does iwrote have an API?

Yes. iwrote publishes one small API, for reading a certificate and checking it without taking iwrote’s word for it. It needs no key and no account. Everything else the site does, from certifying to saving a draft to logging in, answers only the page at iwrote.co and is not part of it.

How do I read a certificate as data?

Add certificate.json to the certificate’s address, short or long, and it comes back as JSON:

curl https://iwrote.co/<name>/<id>/certificate.json
curl https://iwrote.co/c/<token>/certificate.json

What comes back is what the certificate’s page says: its heading, its day, its figures, whether it carries the mark (certified), and the record and reading the mark was decided on. It also carries token, the signed link itself. Every other field is iwrote reading the token out to you, and the token is the one to check.

A short address is cached for five minutes, because its writer can retire it. A long one is cached for a day: nothing is looked up to answer it, so there is nothing to retire. A link that does not verify and a short address nobody issued are both a 404. A short address its writer retired is a 410, and says nothing more about the piece.

How do I check that a certificate is real?

Check the Ed25519 signature in its link against the key iwrote publishes, then check that what was signed is a certificate. A token is a base64url JSON payload, a dot, and a base64url Ed25519 signature over the payload exactly as it appears in the link. The payload’s k names the key that signed it, and /.well-known/jwks.json publishes the public half of every key under its kid, as the raw 32 bytes in x. In a browser or in Node:

const token = decodeURIComponent(link.split("/c/").pop());
const dot = token.lastIndexOf(".");
const payload = token.slice(0, dot);
const b64 = (s) => atob(s.replace(/-/g, "+").replace(/_/g, "/"));
const bytes = (s) => Uint8Array.from(b64(s), (c) => c.charCodeAt(0));

const body = JSON.parse(new TextDecoder().decode(bytes(payload)));
const jwks = "https://iwrote.co/.well-known/jwks.json";
const { keys } = await (await fetch(jwks)).json();
const jwk = keys.find((key) => key.kid === body.k);

const key = await crypto.subtle.importKey(
  "raw", bytes(jwk.x), { name: "Ed25519" }, false, ["verify"],
);
const signature = bytes(token.slice(dot + 1));
const signed = new TextEncoder().encode(payload);
const signedByIwrote = await crypto.subtle.verify("Ed25519", key, signature, signed);

const { v, at, r, j } = body;
const certificate = !("t" in body) && v === 1 && typeof at === "number" &&
  Array.isArray(r) && typeof r[2] === "number" && typeof r[3] === "number" &&
  Array.isArray(j) && ["composed", "typed", "assembled", "imported"].includes(j[1]);
const ok = signedByIwrote && certificate;

The check after the signature matters as much as the signature. The same key signs the receipts iwrote hands out while a piece is being written, to anybody who asks, so a check that stopped at signedByIwrote would pass a receipt as a certificate. A receipt carries a t; a certificate carries none, and has the shape the lines above ask for, which is the shape iwrote itself requires before it opens one.

Nothing in the payload should be believed until ok is true. A k of "dev" is iwrote’s development key, which is published so that anybody can sign with it, and proves nothing. A payload with no k predates published keys, and only iwrote can check it.

What the signature proves is narrow: that the link says what iwrote signed. The counts in it were taken by iwrote’s page in the writer’s own browser. What a certificate cannot prove says the rest.

How do I check when a certificate was issued?

Check its timestamp.tsr, an RFC 3161 timestamp from a service iwrote does not run, with any RFC 3161 tool. When a certificate is issued at a short address, iwrote asks that service to sign the SHA-256 of its token with the service’s own clock. The reply is kept beside the certificate as timestamp.tsr, and certificate.json names the service under timestamp.by. With OpenSSL:

curl -O https://iwrote.co/<name>/<id>/timestamp.tsr
printf %s '<token>' > token
openssl ts -verify -in timestamp.tsr -data token -CAfile /etc/ssl/cert.pem

The last argument is wherever your system keeps the roots it trusts. A certificate issued while the service could not be reached has no timestamp yet, and its timestamp.tsr is a 404 until it does: iwrote asks again every fifteen minutes, so the time the service signs can be later than the moment the certificate was issued.

How do I show a certificate on another page?

With the badge and the card beside it, or through oEmbed. Beside every certificate are badge.png and badge.svg, the badge a writer puts under a post, and card.png, the 1200 by 630 picture a link unfurls to. /api/oembed answers oEmbed for a certificate’s link, so a page that turns links into widgets shows the badge:

curl "https://iwrote.co/api/oembed?url=https://iwrote.co/<name>/<id>"

What are the rate limits?

Every path here is counted per address, per minute, and the numbers are in the OpenAPI description. Past one, the answer is a 429 with the reason in JSON; wait out the minute.

Can a page on another site call it?

Yes. certificate.json, the keys and oEmbed answer a cross-origin caller, so a page on another site can check a link from its reader’s own browser.

Something here wrong, or missing? Write to arpan@iwrote.co.