vitna.ai/docs/api/v1/verification/keys Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/api/v1/verification/keys
> Raw Markdown: https://vitna.ai/docs/api/v1/verification/keys.md
> Corpus index: https://vitna.ai/llms.txt

# Signing keys

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

```
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

| Field | Meaning |
|---|---|
| `purpose` | `record` signs each day's Merkle root; `policy` signs the configs and policies emitted for customers |
| `algorithm` | Read off the key itself. `null` for a row that does not parse as a key |
| `publicKey` | Base64 SPKI DER, the shape `VITNA_PUBLIC_KEY` pins |
| `fingerprint` | Lowercase hex sha256 of the DER bytes: decode `publicKey` from base64 and hash what comes out |
| `enteredServiceAt` | When the key was registered, or when it first signed a root for a `record` key nobody registered |
| `retiredAt`, `retiredReason` | Both `null` while the key is in service. The reason is the operator's text, published as written |
| `signed.attestations` | Attestation rows in the record this key signed, all of them. [`/attestations`](attestations.md) serves the newest 30, so it checks a recent root's key rather than the whole count |
| `signed.artifacts` | Configs and policies this key signed for customers. Absent, and the note says so, where the instance cannot count them |
| `policyKey` | The 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](../../../operations/key-rotation.md).

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`](attestations.md) 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.
Human Machine Shift+M