---
title: "Create a rotation_attempt_descriptor (writer)"
method: POST
path: "/vaults/v1/{vault_id}/rotation-attempts"
tags: ["vault"]
---

# Create a rotation_attempt_descriptor (writer)

`POST /vaults/v1/{vault_id}/rotation-attempts`

## Request

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

Writer (`gitvault.writer`, protocol rev 42 D195/D199). The FIRST write of any epoch rotation attempt, required BEFORE any `key_envelope` upload session for that attempt. The descriptor carries no `reason`, so the reason's authority is enforced when the rotate_epoch head is admitted: `reason:"member_removed"` needs gitvault.writer only, every other reason needs gitvault.rotate (owner + step-up). Body is the complete writer-signed `rotation_attempt_descriptor` object; the gateway verifies the writer signature against the vault's registered creator key and performs a create-only compare-and-swap on the deterministic `rotation_id` — a byte-identical resubmission is an idempotent replay (`200`), a byte-distinct descriptor claiming the SAME `rotation_id` is refused `409 ATTEMPT_DESCRIPTOR_CONFLICT`.

## Path parameters

- `vault_id` string, required

## Headers

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

## Request body

- object: The complete, writer-signed `rotation_attempt_descriptor` object (protocol schemas/rotation_attempt_descriptor.json).

## Response `200`

Idempotent replay of an identical, already-stored descriptor

- object
  - `rotation_id` string
  - `descriptor` object
  - `deduplicated` boolean

## Other responses

- `201`: A fresh rotation attempt was created
- `400`: VALIDATION_FAILED — the descriptor fails its own schema
- `403`: VAULT_ACCESS_DENIED — not authorized for this vault, no active allocation, or the writer signature does not verify
- `409`: ATTEMPT_DESCRIPTOR_CONFLICT — a byte-distinct descriptor already claims this rotation_id

---

[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)