---
title: "Read the vault record"
method: GET
path: "/vaults/v1/{vault_id}"
tags: ["vault"]
---

# Read the vault record

`GET /vaults/v1/{vault_id}`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/vaults/v1/{vault_id}`
- Auth: one of:
  - API key in header `SIGN-IN-WITH-X`
  - HTTP bearer
  - HTTP bearer

Policy, allocation generation + the signed allocation receipt copy, the chain tip, admitted counts, storage + maintenance state, `warnings[]` (e.g. the persistent grandfathered-policy warning), and (vault-multi-writer rev 47) the vault's chain-admitted writer set (`writer_set`), members who could become writers but aren't yet (`pending_writers`, with `pending_writers_skipped` naming why that list is empty on a vault that cannot admit one), members who can't right now and why (`ineligible_members`), and whether the vault has lost its last writer (`read_only_terminal`). Ledger figures exactly — never estimates. Never lifecycle-gated.

## Path parameters

- `vault_id` string, required

## Headers

- `SIGN-IN-WITH-X` string, required

## Response `200`

Vault record

- object
  - `repo_id` string
  - `project_id` string
  - `org_id` string, uuid
  - `vault_policy` 'required' | 'grandfathered', nullable
  - `vault_policy_version` string
  - `vault_policy_changed_at` string, date-time, nullable
  - `allocation_generation` string
  - `allocation` object, nullable
  - `allocation_sha256` string, nullable
  - `storage_profile` 'managed' | 'byo': vault-byo-primary-bucket (D220). Absent or `managed` is byte-identical to every vault allocated before this field existed. Chosen ONLY at allocation in v1 — no route flips it on an existing vault.
  - `byo_destination` string, nullable: Present iff storage_profile is `byo`; the destination address only (bucket/prefix/endpoint-shaped), never credential material of any kind.
  - `newest_generation` string, nullable
  - `genesis_admitted_at` string, date-time, nullable
  - `latest_effective_admitted_at` string, date-time, nullable
  - `admitted_generations` string
  - `authorization_epoch_installed_at` string, date-time, nullable
  - `gc_epoch` string
  - `repair_version` string
  - `repair_fence_state` string
  - `project_deleted_at` string, date-time, nullable: When the vault's project has been deleted, the instant it was; null while the project is live. A vault OUTLIVES its project: deleting a project does not delete, expire, or unbill its vault, so this field plus the vault_project_deleted warning are the only signals distinguishing a retained vault from a live one. Null is also returned when the project row is gone entirely — the instant is unknown, never invented — in which case the warning still fires.
  - `storage` object
  - `maintenance` object
  - `warnings` object[]: Persistent advisories. `vault_policy_grandfathered` when deploys activate without a vaulted capture; `vault_project_deleted` when the vault's project is gone — its history still restores, its source_bytes still count against pooled storage, and no client command removes it. Both can appear together.
    - `kind` 'vault_policy_grandfathered' | 'vault_project_deleted'
    - `message` string
  - `created_at` string, date-time, nullable
  - `writer_set` object: vault-multi-writer rev 47. The vault's chain-admitted writer set as of the latest commit — the SAME projection `add_writer_key`/`rotate_epoch{writer_set_update}` advance.
    - `version` string: Monotonic hex16 writer-set version, advanced by every admitted `add_writer_key`/`writer_set_update`.
    - `sha256` string, nullable: Canonical digest of the writer set at this version; `null` only for a pre-rev-47 vault that hasn't yet self-healed its version-0 projection.
    - `writers` object[]: Ordered by admitted_generation, never insertion order.
      - `writer_key_id` string
      - `signing_pubkey` string
      - `principal_id` string, uuid, nullable
  - `pending_writers` object[]: vault-multi-writer rev 47. Active org members (role developer+) with a published, possession-verified signing key that is NOT yet in writer_set — the set the gitvault_writer_pending feed event names. Drive add_writer_key{"writer"} to admit one.
    - `principal_id` string, uuid
    - `display_name` string, nullable
    - `signing_pubkey` string
  - `pending_writers_skipped` 'byo_single_writer' | 'null', nullable: vault-byo-primary-bucket D11. Why pending_writers is EMPTY on a vault whose org has writer-eligible members waiting. "byo_single_writer" on a bring-your-own-bucket vault — it admits exactly one writer in v1, because its key envelopes live only in the customer's bucket, so a reconcile skips it rather than driving an add_writer_key the admission door refuses with 409 VAULT_BYO_SINGLE_WRITER. null whenever pending_writers means what it says.
  - `ineligible_members` object[]: vault-multi-writer rev 47. Org members who cannot become a writer right now, and why. Derived at read time, never persisted.
    - `principal_id` string, uuid
    - `display_name` string, nullable
    - `reason` 'membership_revoked' | 'role_below_developer' | 'encryption_key_revoked' | 'gateway_blocked_pending_removal'
  - `read_only_terminal` boolean: vault-multi-writer rev 47. True only once a rotate_epoch{writer_set_update, reason:"writer_key_revoked"} explicitly forced the vault's last writer out (the only path to zero writers). The vault still SERVES reads; nothing can push until a new writer is admitted through a recovery path. Driven entirely by the writer chain, never by billing/lifecycle state.
  - `writer_revocation_version` string: vault-multi-writer rev 47 (D6/D227). Decimal-string uint64 counter, bumped by the gateway every time a membership/role/key change gateway-blocks one or more writer keys. A client builds a rotate_epoch{writer_set_update} by freezing this value into rotation_attempt_descriptor.writer_revocation_version at its own admission fence — there is no separate "declare" round-trip for the writer dimension, unlike the encryption side's declareRecipientKeyRevoked.

## Other responses

- `403`: Not authorized (VAULT_ACCESS_DENIED)

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)