Get started

Organisation API keys

Source

List active and revoked organisation API keys without exposing key hashes, and soft-revoke compromised or retired keys with an audit reason.

text
GET /api/v1/org/keys
POST /api/v1/org/keys
POST /api/v1/org/keys/{id}/revoke
text
Authorization: Bearer vitna_key_...
bash
curl -H "authorization: Bearer vitna_key_..." https://vitna.ai/api/v1/org/keys

curl -X POST https://vitna.ai/api/v1/org/keys/9/revoke \
  -H "authorization: Bearer vitna_key_..." \
  -H "content-type: application/json" \
  -d '{"reason": "Rotated after CI runner migration"}'

Scopes and privilege isolation

Each key carries one immutable scope:

  • push (vitna_push_...) submits usage ledgers (POST /api/v1/usage), collects signed artifacts (GET /api/v1/artifacts) and reads control-plane state (GET /api/v1/org/*).
  • router (vitna_push_...) calls the hosted router and holds zero control-plane access.
  • platform (vitna_key_...) calls Vitna's hosted APIs and reads and writes the organisation control plane (GET and POST /api/v1/org/*).

No web-facing database role holds INSERT on site.api_key (drizzle/0043), so POST /api/v1/org/keys answers 403 passkey_ceremony_required. Owners mint platform keys (vitna_key_...) directly in /console/settings by confirming a request with an approved WebAuthn passkey (settled by vitna_minter, sealed to the browser's ephemeral key), or an operator mints a key at the prompt:

bash
npm run org:key:create -- --org convexity --scope platform --label "control-plane, owner"

vitna_auth holds column-level SELECT on site.api_key excluding token_sha256, so no query on this surface can read a key hash back after minting. Revoking a key (POST /api/v1/org/keys/{id}/revoke) sets revoked_at and revoked_reason without deleting the audit row, and a database trigger prevents reviving a revoked row.

Listing response

json
{
  "data": [
    {
      "id": 9,
      "orgId": "convexity",
      "label": "ci-policy-sync",
      "scope": "platform",
      "status": "active",
      "createdAt": "2026-09-14T12:00:00.000Z",
      "revokedAt": null,
      "revokedReason": null
    }
  ],
  "meta": {
    "generatedAt": "2026-09-14T12:00:00.000Z",
    "orgId": "convexity",
    "count": 1,
    "activeCount": 1
  }
}