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

# Organisation API keys

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

```
GET /api/v1/org/keys
POST /api/v1/org/keys
POST /api/v1/org/keys/{id}/revoke
```

```
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
  }
}
```
Human Machine Shift+M