Get started

Signing keys

Source

Every key the record acknowledges, what each one is for, whether it has been retired, and how much it provably signed.

text
GET /api/v1/keys
GET /api/v1/keys/policy-key.pub
bash
curl https://vitna.ai/api/v1/keys
curl -s https://vitna.ai/api/v1/keys/policy-key.pub

Response

json
{
  "keys": [
    {
      "purpose": "record",
      "algorithm": "ed25519",
      "publicKey": "MCowBQYDK2VwAyEA...",
      "fingerprint": "5d0c3f...",
      "enteredServiceAt": "2026-08-01T04:00:00.000Z",
      "retiredAt": null,
      "retiredReason": null,
      "signed": { "attestations": 43, "artifacts": 0 }
    },
    {
      "purpose": "policy",
      "algorithm": "ed25519",
      "publicKey": "MCowBQYDK2VwAyEA...",
      "fingerprint": "a81e07...",
      "enteredServiceAt": "2026-09-02T12:00:00.000Z",
      "retiredAt": null,
      "retiredReason": null,
      "signed": { "attestations": 0, "artifacts": 7 }
    }
  ],
  "policyKey": "MCowBQYDK2VwAyEA...",
  "policyKeyFile": "/api/v1/keys/policy-key.pub",
  "note": "policyKey is the value a runtime pins as VITNA_PUBLIC_KEY. A retired key stays listed with its date and reason, because a file it signed is still checkable against it.",
  "meta": { "generatedAt": "...", "source": "database", "count": 2 }
}

Oldest first. Retired keys are listed, with the date and the reason, because a file signed last year by a key since retired is still a file Vitna signed.

Fields

FieldMeaning
purposerecord signs each day's Merkle root; policy signs the configs and policies emitted for customers
algorithmRead off the key itself. null for a row that does not parse as a key
publicKeyBase64 SPKI DER, the shape VITNA_PUBLIC_KEY pins
fingerprintLowercase hex sha256 of the DER bytes: decode publicKey from base64 and hash what comes out
enteredServiceAtWhen the key was registered, or when it first signed a root for a record key nobody registered
retiredAt, retiredReasonBoth null while the key is in service. The reason is the operator's text, published as written
signed.attestationsAttestation rows in the record this key signed, all of them. `/attestations` serves the newest 30, so it checks a recent root's key rather than the whole count
signed.artifactsConfigs and policies this key signed for customers. Absent, and the note says so, where the instance cannot count them
policyKeyThe value a runtime pins, or null when no key is registered to sign policies

policyKey is what a runtime pins, and it can be two keys

Ordinarily one key. During a changeover two policy keys are current at once, and policyKey lists both, comma separated in the order they entered service, which VITNA_PUBLIC_KEY accepts as a set. The runbook for that is rotating a signing key.

A record key is never offered here. It signs the public record's roots, and a runtime that pinned it would be trusting the wrong signer.

No policy key is an answer

A register with no key registered to sign policies answers 200 with policyKey: null and a note saying so. It is not a 404: "there is no policy key yet" is the fact somebody about to pin one needs, and a 404 reads as a wrong address.

policy-key.pub

The same policyKey, as one line of text/plain, so it can be read straight into the variable:

bash
VITNA_PUBLIC_KEY="$(curl -s https://vitna.ai/api/v1/keys/policy-key.pub)"

When no key is registered to sign policies it answers 404 with the code no_policy_key in the error envelope, because a file has nothing to be when there is no key.

Fetching the key you will verify against from the signer's own site is a weaker out-of-band channel than reading it off /console/deployment, where each signed policy prints the key that signed it. Compare the two, or compare the fingerprint with one somebody at Vitna read you, before you trust either.

Serving the snapshot

Answers 200 with keys: null, policyKey: null and a note pointing at the live record, the way `/attestations` does. null rather than [], because an empty list would read as "the record has no keys". policy-key.pub answers 503 with no_record.

Caching

public, max-age=60, for both, with no stale-while-revalidate. Most of v1 may serve an hour-old answer while it revalidates, and a key set cannot: a planned rotation gives days of notice, but a compromise retires a key at once, and a copy an hour old would still offer the retired key to pin. A retirement reaches every reader within the minute.