Get started

Headless artifact signing requests

Source

Queue an asynchronous request for the isolated signer to rebuild and Ed25519-sign your organisation's standing routing policy or environment config, and poll until the artifact settles.

text
GET /api/v1/org/artifact-requests
POST /api/v1/org/artifact-requests
GET /api/v1/org/artifact-requests/{id}
text
Authorization: Bearer vitna_push_...
bash
curl -X POST https://vitna.ai/api/v1/org/artifact-requests \
  -H "authorization: Bearer vitna_push_..." \
  -H "content-type: application/json" \
  -d '{
    "kind": "policy",
    "decisionId": 18,
    "requestedBy": "github-actions/deploy-routing"
  }'

curl -H "authorization: Bearer vitna_push_..." \
  https://vitna.ai/api/v1/org/artifact-requests/7

Ask-only security boundary

Reads (GET) accept either a platform or push key. Queueing an ask (POST) requires a platform key (vitna_key_...) and answers 202 when accepted onto aperture.artifact_request.

A signing request names only kind (policy or config) and an optional decisionId ("as of this accepted decision"). It never accepts document bytes: supplying body, bytes, document, policy, config or signature answers 400 bytes_forbidden, so the isolated vitna_signer daemon rebuilds every signed artifact from accepted decisions in the database rather than acting as a signing oracle.

At most one pending request sits on the queue per organisation at a time (409 already_pending returns the existing pollUrl). Once state moves to signed, fetch the canonical signed bytes from artifact.body (/api/v1/artifacts/{id}).

Response shape

json
{
  "orgId": "convexity",
  "request": {
    "id": 7,
    "orgId": "convexity",
    "kind": "policy",
    "decisionId": 18,
    "requestedBy": "api-key:4 (github-actions/deploy-routing)",
    "state": "signed",
    "createdAt": "2026-09-14T18:30:00.000Z",
    "settledAt": "2026-09-14T18:30:04.000Z",
    "pollUrl": "/api/v1/org/artifact-requests/7",
    "artifact": {
      "id": 12,
      "kind": "policy",
      "outcome": "signed",
      "at": "2026-09-14T18:30:04.000Z",
      "digest": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "decisions": [18],
      "publicKey": "MCowBQYDK2VwAyEA...",
      "refusedBecause": null,
      "body": "/api/v1/artifacts/12"
    }
  },
  "meta": {
    "generatedAt": "2026-09-14T18:30:05.000Z"
  }
}