Get started

Collecting a signed artifact

Source

GET /api/v1/artifacts lists what has been signed for your organisation, and GET /api/v1/artifacts/{id} hands over the bytes, exactly as they were signed.

text
GET /api/v1/artifacts
GET /api/v1/artifacts/{id}
text
Authorization: Bearer vitna_push_...
bash
curl -H "authorization: Bearer vitna_push_..." https://vitna.ai/api/v1/artifacts
curl -H "authorization: Bearer vitna_push_..." https://vitna.ai/api/v1/artifacts/12 -o policy.json

This is how a signed policy reaches the machine that runs it without anybody at Vitna running a command. Before it existed, aperture:sign wrote the bytes to a row and only an operator could read them out, which is a different operator doing the same manual step.

Two acts, two credentials, and neither can do the other

Asking for an artifact is a write and it does not happen here. An owner of the organisation asks at /console/deployment, signed in, through a role that may write on their say-so. The signer answers on its own timer, rebuilding the document from the record rather than signing anything it was handed.

Collecting is a read, and it happens here, with the organisation's own key.

A person signed in to the organisation, owner or member, collects the same bytes from /console/deployment instead, which also prints the key that signed each file. This route is for a machine with no session: a CI job, or a deploy script.

The route checks the key through the one database role that checks org keys, and reads the artifacts through a role that is read-only at the role level and cannot see a key at all. Neither can ask for an artifact, settle a request or write one. A leaked org key can take away what was already signed. It cannot make Vitna sign anything.

The key

An org key with the push scope, minted once by an operator:

bash
npm run org:key:create -- --org convexity --label "CI, collecting policies"

A router key is refused here and says so. The two are separate capabilities on purpose: a router key spends money at a provider, and reading what your register decided is not that. A push key presented to the router is refused the same way.

A request with no key, or with a key the record does not hold or has revoked, answers 401 with "code": "unauthorized" beside the refusals, the same code the rest of v1 uses for the same refusal.

A revoked key is told the date it was revoked and not the reason. The likeliest bearer of a revoked key is whoever found it, and a member of the organisation reads the reason beside the key at /console/settings.

What a listing answers

json
{
  "org": "convexity",
  "artifacts": [
    {
      "id": 12,
      "kind": "policy",
      "outcome": "signed",
      "at": "2026-08-31T12:04:11.000Z",
      "digest": "9f2c...",
      "decisions": [41],
      "publicKey": "MCowBQYDK2Vw...",
      "refusedBecause": null,
      "body": "/api/v1/artifacts/12"
    }
  ],
  "note": "every signed row is bytes you can take away, and every refused row is a question that was asked and declined."
}

Refused rows are in the listing. An organisation that asked for an artifact and did not get one is owed the reason, and a listing showing only successes would answer "what have we signed" rather than "what did we ask for". A refused row carries refusedBecause and no digest, and collecting it answers 409 with the reason rather than handing over a file that is not one.

publicKey is which key signed. It is the public half, the record publishes it at /witness, and you need it to know which of the keys the record acknowledges to check this against.

The newest fifty are listed, newest first.

What a collection answers

The bytes, with content-type: application/json, a filename in content-disposition, and the digest in x-vitna-digest so a caller can check the transfer without parsing the document first.

Byte for byte. Not re-serialised, not pretty-printed, not wrapped in an envelope. The signature covers these exact bytes, so anything that touched them on the way out would break the one check you are meant to run:

bash
npm run aperture:policy -- --verify policy.json

An id belonging to another organisation answers 404, not 403. A 403 would confirm the id exists, which turns a list of guesses into a census of who has signed what.

What "short-lived" means here, precisely

RUNTIME.md open decision 9 calls this an authenticated short-lived download, and it is worth saying what that turned out to be rather than implying a mechanism that is not here.

There is no signed URL and no download token. Every request carries the organisation's key and is authorised on the spot, so there is no artifact URL that works without the credential, and therefore nothing to expire. That is a different property from a short expiry on a link anybody holding it can use, and a stronger one, so it is described rather than borrowed.

What this does not do

It does not fetch a policy for a running runtime. Nothing here is in a request path and no runtime calls it while serving. A runtime loads its policy from local disk at boot; putting the file there between deploys is a management-plane act, and a runtime that fetched its policy per request would put Vitna's availability inside its own, which is the dependency the whole architecture refuses.

It does not sign. The key is not in this process, and tests/environment-boundary.test.mjs fails if anything a page can import so much as names it.